You are on page 1of 1400

Parallels Plesk Panel

Copyright Notice
ISBN: N/A Parallels 660 SW 39th Street Suite 205 Renton, Washington 98057 USA Phone: +1 (425) 282 6400 Fax: +1 (425) 282 6444 Copyright 1999-2008, Parallels, Inc. All rights reserved Distribution of this work or derivative of this work in any form is prohibited unless prior written permission is obtained from the copyright holder. Patented technology protected by U.S.Patents 7,328,225; 7,325,017; 7,293,033; 7,099,948; 7,076,633. Patents pending in the U.S. Product and service names mentioned herein are the trademarks of their respective owners.

Contents
Preface 10

About This Document .................................................................................................................. 10 Who Should Read This Document .............................................................................................. 11 Prerequisites for This Document ................................................................................................. 11 Typographical Conventions ......................................................................................................... 11 Feedback ..................................................................................................................................... 12

Resellers in Plesk 9: Backward Compatibility Before Using The Reference

13 14

XSD Representation Conventions ............................................................................................... 14 Data Types .................................................................................................................................. 15 API RPC Schemas Location ....................................................................................................... 16 How to Analyze API RPC Schema .............................................................................................. 16

API RPC Evolution API RPC Change History

20 22

Plesk 9 ......................................................................................................................................... 23

XML Schemas for API RPC Operators

29

v.1.4.0.0 ....................................................................................................................................... 29 v.1.4.1.0 ....................................................................................................................................... 31 v.1.4.1.1 ....................................................................................................................................... 32 v.1.4.1.2 ....................................................................................................................................... 34 v.1.4.2.0 ....................................................................................................................................... 35 v.1.5.0.0 ....................................................................................................................................... 37 v.1.5.1.0 ....................................................................................................................................... 39 v.1.5.2.0 ....................................................................................................................................... 41 v.1.5.2.1 ....................................................................................................................................... 43 v.1.6.0.0 ....................................................................................................................................... 45

Representation of Object Descriptor

47

Filters of Descriptors.................................................................................................................... 48 Property Descriptor...................................................................................................................... 49 Extension of Permissions Descriptor ................................................................................ 51 Extension of Hosting Settings Descriptor .......................................................................... 52 Extension of Limits Descriptor ........................................................................................... 54 Bind Parameters .......................................................................................................................... 55

Supported Operations

57

Preface Managing Client Accounts ........................................................................................................... 58 Filtering Issues .................................................................................................................. 60 Client Settings ................................................................................................................... 63 Creating Client Account .................................................................................................... 81 Getting Information About Client Accounts ....................................................................... 87 Deleting Client Accounts ................................................................................................... 95 Setting Client Account Properties ................................................................................... 100 Adding IP Addresses to Clients IP Pool ......................................................................... 107 Removing IP Addresses from the Clients IP Pool .......................................................... 109 Listing Buttons Displayed on the Clients Page in Control Panel .................................... 112 Retrieving Descriptor of Limits ........................................................................................ 119 Retrieving Descriptor of Permissions .............................................................................. 125 Upgrading Client Account to Reseller Account ............................................................... 129 Changing Client Account Owner ..................................................................................... 132 Managing Client Templates ....................................................................................................... 135 Client Template Settings ................................................................................................. 136 Filtering Issues ................................................................................................................ 142 Creating Client Template ................................................................................................ 144 Retrieving Information on Client Templates .................................................................... 148 Removing Client Templates ............................................................................................ 153 Updating Client Template Settings ................................................................................. 157 Managing Database Servers ..................................................................................................... 162 Adding Database Server ................................................................................................. 164 Changing Database Server Preferences ........................................................................ 170 Detaching Database Servers .......................................................................................... 175 Setting Default Database Server..................................................................................... 180 Retrieving Default Database Server Info ........................................................................ 184 Retrieving Database Server Parameters ........................................................................ 189 Retrieving Supported Types Of Databases .................................................................... 195 Retrieving Local Database Servers Info ......................................................................... 198 Managing Databases ................................................................................................................ 202 Filtering Issues ................................................................................................................ 204 Creating Databases ........................................................................................................ 205 Deleting Databases ......................................................................................................... 211 Creating Database Users ................................................................................................ 216 Assigning Database Administrator .................................................................................. 221 Retrieving Database Administrator Info .......................................................................... 224 Retrieving Information About Databases ........................................................................ 230 Changing Database User Credentials ............................................................................ 237 Retrieving Database Users Info ...................................................................................... 242 Deleting Database Users ................................................................................................ 246 Managing Desktop Presets ....................................................................................................... 251 Changing Plesk Administrator Preset ............................................................................. 252 Choosing Default Preset ................................................................................................. 255 Retrieving Preset Preferences ........................................................................................ 260 Adding Preset .................................................................................................................. 265 Removing Preset ............................................................................................................. 270 Managing DNS .......................................................................................................................... 276 Filtering Issues ................................................................................................................ 279 Managing DNS Records ................................................................................................. 282 Managing ACL................................................................................................................. 304 Managing SOA Records and Zone Parameters ............................................................. 315 Managing Name Servers ................................................................................................ 329 Managing Local or Remote DNS Servers ....................................................................... 350 Managing DNS Recursion ............................................................................................... 368 Managing Domain Accounts ..................................................................................................... 377 Filtering Issues ................................................................................................................ 379 Domain Settings .............................................................................................................. 383 Creating Domain Account ............................................................................................... 422

Preface Getting Information About Domain Accounts .................................................................. 429 Deleting Domain Accounts .............................................................................................. 440 Setting Domain Parameters ............................................................................................ 445 Getting the Domain Buttons List ..................................................................................... 453 Getting Traffic Usage Information ................................................................................... 459 Setting Domain Traffic Settings ....................................................................................... 468 Retrieving Descriptor of Limits ........................................................................................ 472 Retrieving Descriptor of Permissions .............................................................................. 478 Retrieving Descriptor of Hosting Settings ....................................................................... 482 Managing Domain Aliases ......................................................................................................... 487 Domain Alias Settings ..................................................................................................... 489 Filtering Issues ................................................................................................................ 491 Creating Domain Aliases ................................................................................................. 492 Retrieving Information On Domain Aliases ..................................................................... 497 Updating Domain Aliases Settings .................................................................................. 503 Deleting Domain Aliases ................................................................................................. 508 Renaming Domain Aliases .............................................................................................. 512 Retrieving Information On Manageable Services ........................................................... 515 Managing Domain Templates ................................................................................................... 516 Domain Template Settings .............................................................................................. 517 Filtering Issues ................................................................................................................ 522 Creating Domain Template ............................................................................................. 524 Getting Information On Domain Templates .................................................................... 532 Configuring Domain Template Settings .......................................................................... 539 Deleting Domain Template.............................................................................................. 549 Managing FTP Accounts ........................................................................................................... 555 FTP Account Permissions ............................................................................................... 556 Filtering Issues ................................................................................................................ 556 Creating FTP Accounts ................................................................................................... 560 Retrieving Information On FTP Accounts ....................................................................... 568 Changing FTP Account Settings ..................................................................................... 575 Deleting FTP Accounts ................................................................................................... 582 Managing IP Addresses ............................................................................................................ 587 Adding IP Address .......................................................................................................... 588 Retrieving IP addresses .................................................................................................. 593 Changing Type ................................................................................................................ 596 Removing IP .................................................................................................................... 600 Managing Locales ..................................................................................................................... 605 LP Names........................................................................................................................ 606 Filtering Issues ................................................................................................................ 606 Retrieving List of LP's...................................................................................................... 608 Installing LP ..................................................................................................................... 614 Retrieving Localized Messages ...................................................................................... 617 Removing LP ................................................................................................................... 622 Enabling LP ..................................................................................................................... 627 Disabling LP .................................................................................................................... 632 Locale Codes .................................................................................................................. 637 Managing Log Rotation on Domain ........................................................................................... 640 Log Rotation Settings ...................................................................................................... 641 Filtering Issues ................................................................................................................ 642 Changing Log Rotation Settings ..................................................................................... 644 Retrieving Log Rotation Settings..................................................................................... 650 Enabling Log Rotation Service ........................................................................................ 656 Disabling Log Rotation Service ....................................................................................... 662 Checking Status of Log Rotation Service ....................................................................... 667 Managing Mail on Domain Level ............................................................................................... 673 Mail Service Preferences ................................................................................................ 675 Mail Account Settings ...................................................................................................... 677 Filtering Issues ................................................................................................................ 690

Preface Creating Mail Accounts ................................................................................................... 691 Modifying Mail Account Settings ..................................................................................... 696 Getting Mail Account Settings ......................................................................................... 703 Deleting Mail Accounts .................................................................................................... 708 Enabling/Disabling Mail Service on Domain ................................................................... 712 Setting Mail Service Preferences .................................................................................... 717 Getting Mail Service Preferences.................................................................................... 721 Renaming Mail Accounts ................................................................................................ 725 Managing Mailing Lists .............................................................................................................. 728 Filtering Issues ................................................................................................................ 730 Adding Mailing List .......................................................................................................... 733 Removing Mailing List ..................................................................................................... 739 Adding Subscriber to Mailing List .................................................................................... 744 Retrieving Mailing Lists ................................................................................................... 749 Retrieving Subscribers' Info ............................................................................................ 754 Removing Subscriber ...................................................................................................... 759 Activating Mailing Lists Service ....................................................................................... 764 Deactivating Mailing Lists Service................................................................................... 769 Enabling Mailing List ....................................................................................................... 774 Disabling Mailing List ...................................................................................................... 779 Retrieving Status of Mailing Lists Service ....................................................................... 783 Managing Plesk Backups .......................................................................................................... 789 Remote Storage Settings ................................................................................................ 791 Retrieving Remote Storage Settings ............................................................................... 792 Changing Remote Storage Settings ............................................................................... 797 Creating Domain-level Backup Task ............................................................................... 800 Creating Client-level Backup Task .................................................................................. 805 Creating Reseller-level Backup Task .............................................................................. 809 Creating Server-level Backup Task................................................................................. 813 Retrieving Backup Task Status ....................................................................................... 817 Retrieving List of Local Backups ..................................................................................... 822 Adding Backup to Repository .......................................................................................... 827 Downloading Backup ...................................................................................................... 831 Retrieving Protocols Supported by Backup Manager ..................................................... 834 Cancelling Backup Tasks ................................................................................................ 836 Removing Backup ........................................................................................................... 839 Managing Plesk Server ............................................................................................................. 842 Administrator Personal Information ................................................................................. 844 Server Preferences ......................................................................................................... 847 Getting Supported Protocols ........................................................................................... 850 Performing Initial Server Setup ....................................................................................... 851 Managing Plesk License ................................................................................................. 855 Getting Server Information .............................................................................................. 865 Setting Up Server ............................................................................................................ 897 Managing Plesk Services ................................................................................................ 901 Managing Plesk Updates .......................................................................................................... 905 Checking Updater Status ................................................................................................ 906 Retrieving Plesk Updates ................................................................................................ 908 Retrieving Components List ............................................................................................ 911 Installing Components ..................................................................................................... 916 Updating Plesk ................................................................................................................ 919 Managing Protected Directories ................................................................................................ 922 Filtering Issues ................................................................................................................ 923 Creating Protected Directory ........................................................................................... 926 Changing Protected Directory Properties ....................................................................... 930 Removing Protected Directory ........................................................................................ 938 Retrieving Protected Directory Properties ....................................................................... 942 Creating Protected Directory User .................................................................................. 948 Changing Protected Directory User Settings .................................................................. 952

Preface Removing Protected Directory User ............................................................................... 957 Retrieving Protected Directory User Settings ................................................................. 961 Retrieving Descriptor of Protected Directory Properties ................................................. 965 Managing Reseller Accounts ..................................................................................................... 970 Reseller Settings ............................................................................................................. 972 Filtering Issues ................................................................................................................ 980 Creating Reseller Accounts ............................................................................................. 982 Setting Reseller Account Properties ............................................................................... 987 Retrieving Information on Reseller Accounts .................................................................. 992 Removing Reseller Accounts .......................................................................................... 999 Adding IP Addresses to Reseller's IP Pool ................................................................... 1003 Removing IP Addresses from Reseller's IP Pool .......................................................... 1007 Changing IP Address Type in Reseller's IP Pool .......................................................... 1010 Changing Types of Application Packages in Reseller's Application Pool ..................... 1013 Viewing Buttons Displayed on Reseller's Home Page in Control Panel ...................... 1016 Retrieving Descriptor of Limits ...................................................................................... 1021 Retrieving Descriptor of Permissions ............................................................................ 1024 Downgrading Reseller Account to Client Account ........................................................ 1027 Managing Reseller Templates ................................................................................................. 1030 Reseller Template Settings ........................................................................................... 1031 Filtering Issues .............................................................................................................. 1034 Creating Reseller Template .......................................................................................... 1035 Retrieving Information About Reseller Templates ........................................................ 1039 Removing Reseller Templates ...................................................................................... 1043 Setting Reseller Template Properties ........................................................................... 1046 Managing Secret Keys ............................................................................................................ 1050 Creating Secret Key ...................................................................................................... 1051 Retrieving Info on Secret Keys...................................................................................... 1055 Removing Secret Key ................................................................................................... 1060 Managing Sessions ................................................................................................................. 1065 Retrieving Sessions List ................................................................................................ 1065 Terminating Session ..................................................................................................... 1068 Managing Web Applications .................................................................................................... 1072 History of Changes ........................................................................................................ 1074 Web Application Properties ........................................................................................... 1075 Retrieving List of All Web Applications ......................................................................... 1076 Viewing Application Pool ............................................................................................... 1079 Adding Web Application to Application Pool ................................................................. 1083 Removing Web Applications ......................................................................................... 1087 Retrieving List of Packages Available For Domain ....................................................... 1091 Changing Properties of Web Application ...................................................................... 1096 Retrieving Web application Requirements .................................................................... 1100 Installing Web Application ............................................................................................. 1106 Managing Spam Filtering Service ........................................................................................... 1111 Filtering Issues .............................................................................................................. 1113 About Spam Filtering ..................................................................................................... 1115 Adding Pattern............................................................................................................... 1119 Removing Pattern ......................................................................................................... 1125 Retrieving Patterns ........................................................................................................ 1130 Retrieving Info on Spam Filtering service ..................................................................... 1134 Setting Spam Filtering Preferences .............................................................................. 1140 Retrieving Available Spam Filtering Preferences.......................................................... 1146 Retrieving Allowed Lists ................................................................................................ 1152 Checking Status of Spam Filtering Service ................................................................... 1158 Managing SSL Certificates ...................................................................................................... 1161 Installing Certificate ....................................................................................................... 1162 Deleting Certificate ........................................................................................................ 1168 Generating Certificate ................................................................................................... 1173 Managing SSO Service ........................................................................................................... 1178

Preface Filtering Issues .............................................................................................................. 1179 Enabling SSO Service ................................................................................................... 1181 Disabling SSO Service .................................................................................................. 1184 Registering Plesk in IdP ................................................................................................ 1186 Retrieving SSO Service Preferences ............................................................................ 1189 Configuring SSO Branding ............................................................................................ 1191 Adding Delegation Rule ................................................................................................ 1212 Removing Delegation Rule ........................................................................................... 1215 Managing Subdomains ............................................................................................................ 1218 Filtering Issues .............................................................................................................. 1219 Subdomain Properties ................................................................................................... 1220 Creating Subdomain ..................................................................................................... 1222 Retrieving Information on Subdomain ........................................................................... 1226 Changing Subdomain Settings ...................................................................................... 1232 Removing Subdomain ................................................................................................... 1235 Renaming Subdomain ................................................................................................... 1238 Changing Parent Domain .............................................................................................. 1241 Managing User Interface ......................................................................................................... 1245 Setting Up Controls Visibility ......................................................................................... 1246 Managing Custom Buttons ............................................................................................ 1249 Managing Virtual Directories ................................................................................................... 1267 Virtual Directory Settings ............................................................................................... 1268 Creating Virtual Directories ........................................................................................... 1275 Removing Virtual Directories......................................................................................... 1280 Managing Web Users .............................................................................................................. 1284 Web User Settings and Preferences ............................................................................. 1285 Filtering Issues .............................................................................................................. 1289 Creating Web Users ...................................................................................................... 1291 Deleting Web Users ...................................................................................................... 1296 Updating Web User Settings ......................................................................................... 1302 Retrieving Web Users Settings .................................................................................... 1308 Retrieving Web Users Preferences ............................................................................... 1314 Updating Web Users Preferences................................................................................. 1319 Migrating Domain And Client Accounts ................................................................................... 1325 IP Addresses Mapping .................................................................................................. 1327 Databases Mapping ...................................................................................................... 1329 Checking Plesk Migration Manager Installation ............................................................ 1331 Retrieving File System Information ............................................................................... 1333 Starting Migration .......................................................................................................... 1335 Retrieving Migration Status ........................................................................................... 1350 Stopping Migration ........................................................................................................ 1356 Retrieving Action Log Data ...................................................................................................... 1360 Retrieving Action Log .................................................................................................... 1361 Retrieving ID of Last Action ........................................................................................... 1366 Uploading Files to Server ........................................................................................................ 1368 Uploading Files Using cURL ......................................................................................... 1368 Uploading Files Using PHP ........................................................................................... 1370 Uploading Files Using .NET .......................................................................................... 1371 Response Packet Structure .......................................................................................... 1375 Response Samples ....................................................................................................... 1376

Preface

Error Codes

1377

Reduced List of Error Codes ................................................................................................... 1378 Complete List of Error Codes .................................................................................................. 1379 Common errors ............................................................................................................. 1383 Client Operations .......................................................................................................... 1384 Domain Operations ....................................................................................................... 1386 IP Operations ................................................................................................................ 1388 DNS Operations ............................................................................................................ 1390 Server Operations ......................................................................................................... 1392 Web Application Operations .......................................................................................... 1394 Email Operations ........................................................................................................... 1395 Certificate Operations ................................................................................................... 1395 UI Operations ................................................................................................................ 1396 Upload Operations ........................................................................................................ 1397 Secret Key Operations .................................................................................................. 1397 Spam Filter Operations ................................................................................................. 1398 Domain Alias Operations .............................................................................................. 1398 Database Server Operations......................................................................................... 1399 Migration Operations ..................................................................................................... 1399

10

Preface

Preface
In this section:
About This Document ........................................................................................ 10 Who Should Read This Document .................................................................... 11 Prerequisites for This Document ....................................................................... 11 Typographical Conventions ............................................................................... 11 Feedback .......................................................................................................... 12

About This Document


This part of Plesk API RPC documentation describes in detail the programming means provided by Plesk API. Chapter Before Using Reference (on page 14) contains information required for proper reading of the reference sections. Chapter Representation of Object Descriptors (see page 47) explains in detail what object descriptors are and how they are implemented in the API RPC protocol. Chapter Supported Operations explains which Plesk objects can be managed programmatically via API RPC, how this can be done, and what particular operations are allowed to different kinds of Plesk users. Chapter API RPC Versions contains references on what XML Schemas are used for each API RPC operation depending on the API RPC version. Chapter Error Codes (see page 1377) provides information on codes of the errors that may occur when using Plesk API RPC protocol.

This document covers the following versions of the API RPC protocol: 1.3.5.1 - 1.6.0.0. In most code samples, the 1.4.2.0 version of the protocol is used. If a feature is supported only in later versions of API RPC, the earliest version of the protocol that supports the feature is used in code samples.

Preface

11

Who Should Read This Document


This part of Plesk API RPC documentation is addressed to the developers who want to implement a kind of a remote Plesk manager or other software capable of managing Plesk objects remotely.

Prerequisites for This Document


Users of this document should be familiar with the following: Plesk functionality and business logic. Plesk API RPC protocol (idea, usage). Refer to the Plesk API RPC Developer's Guide. HTTP messages (types, structure). Refer to the RFC 2616 (http://www.ietf.org/rfc/rfc2616.txt). XML basics (idea, syntax, elements, attributes). Refer to the W3Schools XML Tutorial (http://www.w3schools.com/xml/default.asp). XML Schema (idea, simple and complex elements, XSD indicators, data types). Refer to the W3Schools XML Schema Tutorial (http://www.w3schools.com/schema/default.asp).

Typographical Conventions
The following kinds of formatting in the text identify special information.
Formatting convention Special Bold Type of Information Names of operators and operations. Titles of chapters, sections, and subsections found in the other documents. Italics Example Go to the QoS tab. Read the Basic Administration chapter.

Emphasizes the importance of The system supports the so a point, to introduce a term or called wildcard character to designate a command line search. placeholder, which is to be replaced with a real name or value. The names of commands, files, and directories. The license file is located in the httpdocs/common/license s directory.

Monospace

12

Preface On-screen computer output in # ls al /files your command-line sessions; total 14470 source code in XML, C++, or other programming languages. What you type, contrasted with # cd /root/rpms/php on-screen computer output. Names of keys on the keyboard and names of operations on the title page of an operator. Key combinations for which the user must press and hold down one key and then press another. SHIFT, CTRL, ALT

Preformatted

Preformatted Bold CAPITALS

KEY+KEY

CTRL+P, ALT+F4

Feedback
If you have found a mistake in this guide, or if you have suggestions or ideas on how to improve this guide, please send your feedback using the online form at http://www.parallels.com/en/support/usersdoc/. Please include in your report the guide's title, chapter and section titles, and the fragment of text in which you have found an error.

CHAPTER 1

Resellers in Plesk 9: Backward Compatibility


The Plesk 9 backward compatibility prevents malfunctioning of client applications which interact with Plesk 9 through old versions of API RPC(<1.6.0.0) and hence cannot sufficiently accommodate changes in Plesk business logic. For these applications, we modified the behavior of some operations to fit new Plesk business logic. Most modifications are operation specific, some modifications are common for all operations. The common modification are as follows: Plesk Administrator accesses personal objects (domain accounts, domain templates) by specifying admin as a Plesk client login name. Hence, in some situations Plesk Administrator now acts like a Plesk client. We will refer to this client account as to the artificial client account. You cannot modify or remove this account. Plesk reseller accounts are treated as Plesk client accounts.

Each operation-specific modification is described in the corresponding sub-section of the Supported Operations chapter.

CHAPTER 2

Before Using The Reference


This section contains information required for proper reading of the reference sections. The XSD Representation Conventions (on page 14) section explains designations used in graphical representation of XML objects described in the current document. The Data Types (on page 15) section contains classification of object types described in the current document. The API RPC Schemas Location (on page 16) section explains how to access the whole set of XSD schemas, or find a schema for a specific operator supported by the API RPC protocol. The How to Analyze API RPC Schema (on page 16) section explains how to read an XSD schema using user agents or text editors. This can be helpful, if you want to create a valid packet according only to XSD files.

In this chapter:
XSD Representation Conventions ......................................................................14 Data Types ........................................................................................................15 API RPC Schemas Location ..............................................................................16 How to Analyze API RPC Schema .....................................................................16

XSD Representation Conventions


Description of each operation supported by the protocol includes the Request Packet Structure and the Response Packet Structure sections. The first section contains graphical representation of an XML schema used to create a request packet that is to be sent to the server to perform an operation. The second section contains graphical representation of an XML schema used to create a response packet from the server with the result of the operation. To represent the XML schemes graphically, the Altova XMLSpy rules and agreements are used. For details on the rules and agreements, visit the following URL: http://www.altova.com/manual2007/XMLSpy/spyenterprise/contentmodelview.htm.

Before Using The Reference

15

Data Types
Each node of the XML schema is of a specified type. For details on XML data types, visit the following URL: http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/. In API Reference, a node can be of a simple or a complex type. If the type of the node is complex and has a name, the name of the type is followed by a filename. The filename specifies the file where the type is located. If the type is not named, it is called complex in the reference. If the type is simple, it can be a standard type or its modification. A list of standard simple types is presented in the following table.
Type string short integer unsignedInt unsignedLong long base64 boolean byte date dateTime Definition Sequence of 1..255 characters Examples mytext, a, ppp

Integer numbers from -2^15 to 2^15- -167, 2880, 310 1* Integer numbers from -2^31 to 2^31- -16007, 211880, 310010 1 Integer numbers from 0 to 2^32-1 Integer numbers from 0 to 2^64-1 1670031, 3321455232 44322344432

Integer numbers from -2^63 to 2^63- 184467440737095516 1 Base64-encoded arbitrary binary data Binary-valued logic legal literals Integer numbers from -128 to 127 Calendar date. Format YYYY-MMDD Specific instant of time. ISO 8601 extended format YYYY-MMDDThh:mm:ss GTrRddxXRGgh== true, false, 1, 0 1, 0, 126, 100 May the 31st, 1999 is: 1999-05-31 1:20 pm on May the 31st, 1999 for Eastern Standard Time which is 5 hours behind Coordinated Universal Time (UTC) looks as follows: 1999-05-31T13:20:00-05:00

none anySimple

Nodes of this type do not contain any data (so-called blank nodes) Any simple type except none 123, mytext, example123string

* - the number y^n is the number y raised to the n-th power.

16

Before Using The Reference

API RPC Schemas Location


All XSD files which define the format of XML documents for API RPC packets content are packed to the archive schemas.zip and available for downloading at http://download1.parallels.com/Plesk/Plesk9.0/Doc/schemas.zip. The archive contains a separate folder with a set of API RPC schemas for each protocol version supported by Plesk. To know which schemas are used for a specific operator, refer to the XML Schemas for API RPC Operators (on page 29) chapter.

How to Analyze API RPC Schema


The following instructions can help you analyze an XML API schema. If you use API RPC 1.4.0.0 or higher: Start with the main agent_input.xsd schema. It lists all supported operator elements within the packet element. For example,

Before Using The Reference

17

On the above figure, complex data type RequestPacketType lists all operator elements supported in API RPC 1.4.0.0. These operators are: server, client, domain, etc. Each operator has a matching request data type (the type attribute). This data type describes the structure of the operator. To see the structure of a certain operator, you need to find the low-level 'input' schema where its data type is defined. File agent_input.xsd lists all subsequent schemas as follows:

18

Before Using The Reference

The schema name contains the name of the operator you need and the _input suffix. Open the schema matching any operator. It will contain several complex data types, including the request data type specified for the operator. For example, here is the contents of the client_input.xsd schema (v.1.4.0.0) matching the client operator.

The client operator is described by type ServerOperatorType (highlighted). To see its structure, click the + sign to the left and expand the section. Type ServerOperatorType describes the client operator as follows: It lists all operations that can be applied to Plesk Client (get_protos, get, set, srv_man, etc.). The same principle is true for any operator: its request data type (specified in the agent_input.xsd schema) declares operations that can be applied to the relevant object.

Before Using The Reference

19

Each operation element is also presented by a special data type specified in the type attribute. Operation data types are normally defined in the same schema. For example, the set operation (type AdminSetType) is defined in the same client_input.xsd schema as follows:

All nested elements (operation parameters) are described by specific data types. You can find their definitions either in the same schema, or in the included schema:

Thus, when you analyse the schemas, the approach is as follows: start with the main schema to choose the operator and drill down to the subsequent data types that can be found in the included schemas. If you use API RPC 1.3.5.1 or lower, find the required input schema by its name. The schema describes the structure of the XML packet within the packet element: It contains a single operator element that, in turn, contains some operation elements. Operations are structured as described above: Each operation is a complex data type that contains sequences of various parameters. Some parameters are fully defined within the operation element, others have just a complex data type specified against them. Such data types can be defined in the same schema or in some other schema included into this one with the include directive.

20

API RPC Evolution

API RPC Evolution


The table below demonstrates the main stages of Plesk API RPC evolution and enumerates new features added to the protocol along with each new version of Plesk.
API RPC version Plesk version Plesk 7.5.1 for Linux/Unix New supported objects Client DNS record Domain Event logging IP address Server Plesk 7.5.2 for Linux/Unix 1.3.5.0 Plesk 7.5.3 for Linux/Unix Web application SSL certificate Email service Custom button Upload 1.3.5.1 1.4.0.0 Plesk 7.5.4 for Linux/Unix Plesk 7.5.6 for Linux/Unix Database server Desktop Domain alias Migration Secret key Spam filter 1.4.1.0 1.4.1.1 Plesk 8.0 for Linux/Unix, Plesk 7.6 for Windows Plesk 7.6.1 for Windows Client template Domain template Virtual directory

API RPC Evolution

21

API RPC version 1.4.2.0

Plesk version Plesk 8.1 for Linux/Unix, Plesk 8.1 for Windows

New supported objects Database Mailing list Web user Additional FTP account

1.5.0.0

Plesk 8.1.1 for Linux/Unix, Plesk 8.1.1 for Windows

Descriptor Locale Log rotation Session

1.5.1.0

Plesk 8.2 for Linux/Unix, Plesk 8.2 for Windows Plesk 8.3 for Linux/Unix, Plesk 8.3 for Windows Plesk 8.4 for Linux/Unix, Plesk 8.4 for Windows, Plesk 8.6 for Linux/Unix, Plesk 8.6 for Windows Plesk 9.0 for Linux/Unix, Plesk 9.0 for Windows

Backup Protected directory Subdomain none

1.5.2.0 1.5.2.1

1.6.0.0

Reseller Reseller template

CHAPTER 3

API RPC Change History


The following is a summary of changes made to the API RPC protocol since v.1.6.0.0. The changes are listed with the most recent first. The next paragraph explains how these changes are grouped. Changes are first grouped by Plesk version and then are divided into two categories: Changes between two last versions of the protocol (subsection last version->current version) Changes to earlier versions of the protocol caused by changes in logic of a new Plesk version (subsection Changes to Earlier Versions).

These two groups are further categorized by Plesk features that required modifying operators and/or operations. Each set of feature-dependant changes is fit into a separate table and sequenced in alphabetical order. Thus, if you use Plesk 9 through API RPC 1.5.0.0 and want to see changes to API RPC 1.5.0.0 driven by the Plesk 9 backward compatibility feature, refer to subsection Plesk 9 > Changes to Earlier Versions, table "Feature: Plesk 9 backward compatibility". Each feature-dependant table consists of the following columns: Option - defines whether an operator/operation/parameter is added ("+"), modified ("*"), or deprecated ("-"). Operator - contains the name of the operator affected by the feature. Operation - contains the name of the operation affected by the feature. The operation name is omitted in the following cases: New operator is added Operator is removed Feature modifies the behavior of an entire operator Feature modifies the XSD complex type that is not explicitly related to an operation (Example: filters).

Type/File - contains the name of an XSD complex type affected by the feature. This name helps to determine whether request, response or both packet structures are changed. If the complex type name is changed, the new name is given. If an operation description is changed, and new description does not use any named complex types, the XSD file which contains the operation description is given. The type/file name is omitted in the following cases: Operation description is left unaffected. Operation is added or deprecated.

Note: The summary of changes does not explicitly track changes in complex type names

API RPC Change History

23

Parameter - contains the affected parameter. This value is present only if Operation or Type/Filename values are provided. If the operation name or both values are set, the path to the parameter is given relatively the operation node. Otherwise, the path is given relatively to the XML element described by the type. We use XPath notations to address the parameter. Comment - contains short description of a change. In case an operator, operation or parameter is deprecated, this field contains brief instructions on what functionality can be used instead.

In this chapter:
Plesk 9 ...............................................................................................................23

Plesk 9
1.6.0.0 Feature: Resellers
Option + + + + + + + + + + * + + + + Operator client client client client client client client client client client clienttemplate clienttemplate clienttemplate clienttemplate clienttemplate ClientTemplatePref erencesType ClientTemplateAddI nputType ClientTemplateAddI nputType ClientTemplateGetI nputType shared owner-id owner-login owner-id add add get convert-toreseller change-owner clientSelectionFilter owner-id Type clientSelectionFilter owner-login Type clientSelectionFilter guid Type clientAddGenInfo owner-id clientAddGenInfo clientGetGenInfo clientLimits owner-login owner-id resourcepolicy Now resellers can use this operator Operation Type/File Parameter Comment Now resellers can use this operator

add add get

24

API RPC Change History

Option + + + + + * * + + + + + + + + + + +

Operator

Operation

Type/File ClientTemplateGetI nputType ClientTemplateDelI nputType ClientTemplateDelI nputType ClientTemplateSetI nputType ClientTemplateSetI nputType SetDefaultPresetIn putCommandType

Parameter owner-login owner-id owner-login owner-id owner-login type

Comment

clientget template clientdel template clientdel template clientset template clientset template desktop set-default-preset domain domain domain domain domain domain domain domain domain domain domain domain domain domain domain domain domain domaintemplate domaintemplate add add add add add get get set set set

Add "reseller" Now resellers can use this operator

domainFilterType domainFilterType domainFilterType domainFilterType domainFilterType domainFilterType domainFilterType

guid client_id owner-id domain_name Use domainname instead domain-name client_login owner-login /gen_setup/cli ent_id /gen_setup/ow ner-id /gen_setup/ow ner-login Use owner-id instead Use owner-login instead Use owner-id instead

domainGenInfoTyp client_id e domainGenInfoTyp owner-id e setGenSetupType client_id setGenSetupType setGenSetupType domainLimits owner-id owner-login overuse

Use owner-id instead

Use owner-id instead

DomainTemplateAd client-id dInputType DomainTemplateAd owner-id dInputType

Use owner-id instead

API RPC Change History

25

Option + + + + + + + *

Operator domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate domaintemplate event_log

Operation add add get get get get set set set set del del del del get_events

Type/File

Parameter

Comment Use owner-login instead

DomainTemplateAd client-login dInputType DomainTemplateAd owner-login dInputType DomainTemplateG client-id etInputType DomainTemplateG owner-id etInputType DomainTemplateG client-login etInputType DomainTemplateG owner-login etInputType DomainTemplateSe client-id tInputType DomainTemplateSe owner-id tInputType DomainTemplateSe client-login tInputType DomainTemplateSe owner-login tInputType DomanTemplateDe client-id leteInputType DomanTemplateDe owner-id leteInputType DomanTemplateDe client-login leteInputType

Use owner-id instead

Use owner-login instead

Use owner-id instead

Use owner-login instead

Use owner-id instead

Use owner-login instead

DomanTemplateDe owner-login leteInputType EventLogResponse /result/event/cl Classes Type ass reseller_* are added New operator added New operator added

+ +

reseller resellertemplate

Feature: New backup functionality


Option + + Operator backup backup Operation get-remotestorage-settings get-remotestorage-settings Type/File Parameter Comment

BackupGetRemote reseller-id StorageSettingsInp ut BackupGetRemote reseller-login StorageSettingsInp ut

26

API RPC Change History

Option + + + + + + + + + + + + + + + + + + -

Operator backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup

Operation get-remotestorage-settings get-remotestorage-settings set-remotestorage-settings set-remotestorage-settings set-remotestorage-settings set-remotestorage-settings backup-domain backup-domain backup-domain backup-domain backup-domain backup-domain backup-client backup-client backup-client backup-client backup-client backup-client backup-client backup-client backup-client backup-reseller backup-server get-backup-status

Type/File BackupGetRemote StorageSettingsInp ut BackupGetRemote StorageSettingsOut put BackupSetRemote StorageSettingsInp ut BackupSetRemote StorageSettingsInp ut BackupSetRemote StorageSettingsInp ut BackupSetRemote StorageSettingsInp ut BackupDomainInpu t BackupDomainInpu t BackupDomainInpu t BackupDomainInpu t BackupDomainInpu t

Parameter server /result/settings /passive-mode reseller-id reseller-login server /settings/passi ve-mode filename prefix only-hosting only-mail onlyconfiguration

Comment

BackupCommandO /result/task-id utput BackupClientInput filename BackupClientInput domain-id BackupClientInput domain-name BackupClientInput all-domains BackupClientInput prefix BackupClientInput only-hosting BackupClientInput only-mail BackupClientInput onlyconfiguration BackupCommandO /result/task-id utput

Use get-tasksinfo instead

API RPC Change History

27

Option + + +

Operator backup backup backup

Operation get-tasks-info

Type/File

Parameter

Comment

get-local-backup- BackupGetLocalBa reseller-id list ckupListInput get-local-backup- BackupGetLocalBa reseller-login list ckupListInput get-local-backup- BackupGetLocalBa server list ckupListInput put-file import-file download-file download-file download-file download-file stop-backup stop-backup stop-backup stop-backup stop-backup get-backupprocesses remove-file remove-file remove-file remove-file BackupRemoveFile Input BackupRemoveFile Input BackupRemoveFile Input BackupRemoveFile Input domain-id domain-name client-id client-login BackupDownloadFil eInput BackupDownloadFil eInput BackupDownloadFil eInput BackupDownloadFil eInput BackupStopInput BackupStopInput BackupStopInput BackupStopInput BackupStopInput domain-id domain-name client-id client-login domain-id domain-name client-id client-login task-id Use get-tasksinfo instead Use import-file instead

+ + + -

backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup backup

Feature: APS Catalog


+ server serverPrefs aps-catalogurl

28

API RPC Change History

Other updates:
+ + * domaintemplate clienttemplate updater DomainTemplatePr shared eferencesType ClientTemplatePref shared erencesType UpdateType action

get-updates

The upgrade action is added

Changes to Earlier Versions 1.3.5.1-1.5.2.0 Feature: Plesk 9 backward compatibility


Option * Operator client Operation add Type/File Parameter Comment Client account is automatically assigned to Plesk Administrator * client get If you request info on all client accounts, Plesk will return info on all client accounts, reseller accounts and artificial client account. Plesk user hierarchy will not be retained. If you request reseller account statistics, the operation will return total reseller account statistics (including statistics for controlled client accounts). If you remove a reseller account, all client accounts owned by the reseller will also be removed If you request info on domain accounts owned by a reseller, Plesk will return info on only reseller's personal domain accounts, excluding those owned by the reseller's clients. If you request info on all domain accounts, the info on all domain accounts (including the accounts owned by Plesk Administrator) will be returned. Now you can also request Plesk Administrator's or reseller's personal domain templates Each reseller-related action is tracked as a client-related action.

client

get

client

del

domain

get

domain

get

domaintemplate event_log

get

CHAPTER 4

XML Schemas for API RPC Operators


This chapter lists XML schemas that define format of messages sent to and received from Plesk API operators, grouped by the protocol versions. To learn how to access the schemas, refer to the API RPC Schemas Location (on page 16) section. The chapter also contains information on Plesk API RPC evolution which shows how Plesk API is developed: what Plesk version introduced each protocol version, and what were the new managed objects in each version.

In this chapter:
v.1.4.0.0 ............................................................................................................ 29 v.1.4.1.0 ............................................................................................................ 31 v.1.4.1.1 ............................................................................................................ 32 v.1.4.1.2 ............................................................................................................ 34 v.1.4.2.0 ............................................................................................................ 35 v.1.5.0.0 ............................................................................................................ 37 v.1.5.1.0 ............................................................................................................ 39 v.1.5.2.0 ............................................................................................................ 41 v.1.5.2.1 ............................................................................................................ 43 v.1.6.0.0 ............................................................................................................ 45

v.1.4.0.0
Version 1.4.0.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd (./rpc/1.4.0.0/agent_input.xsd). This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.4.0.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATIONS Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd AVAILABLE TO Plesk Administrator Plesk Administrator

30

XML Schemas for API RPC Operators

Database server operations Desktop operations DNS operations

db_server

database_input.xsd, database_output.xsd, plesk_db.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd event_log_input.xsd, event_log_output.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd secret_key_input.xsd, secret_ key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter_input.xsd, spamfilter_output.xsd, plesk_spamfilter.xsd upload_output.xsd

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator

desktop dns

Domain alias operations

domain_alias

Domain operations

domain

Event Logging IP operations Mail operations

event_log ip mail

Migration operations

migration

Secret key operations

secret_key

Plesk Administrator

Server operations

server

Plesk Administrator

Web Application operations Spam filtering

siteapp

Plesk Administrator

spamfilter

Plesk Administrator Plesk Administrator

Upload

upload

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

XML Schemas for API RPC Operators

31

v.1.4.1.0
Version 1.4.1.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.4.1.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATIONS Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd AVAILABLE TO Plesk Administrator

Plesk Administrator

Client template operations Database server operations Desktop operations DNS operations

client-template db_server

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

desktop dns

Domain operations

domain

Domain template operations Domain alias operations

domain-template domain_alias

Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator

Event Logging IP operations Mail operations

event_log ip mail

Migration operations

migration

32

XML Schemas for API RPC Operators

Secret key operations

secret_key

secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter_input.xsd, spamfilter_output.xsd, plesk_spamfilter.xsd upload_output.xsd

Plesk Administrator

Server operations

server

Plesk Administrator

Web Application operations Spam filtering

siteapp

Plesk Administrator

spamfilter

Plesk Administrator Plesk Administrator

Upload

upload

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

v.1.4.1.1
Version 1.4.1.1 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.4.1.1 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations Database server operations Desktop operations DNS operations

client-template db_server

desktop dns

XML Schemas for API RPC Operators

33

Domain operations

domain

domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter_input.xsd, spamfilter_output.xsd, plesk_spamfilter.xsd upload_output.xsd virtdir.xsd

Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

Domain template operations Domain alias operations Event Logging IP operations Mail operations Migration operations

domain-template domain_alias

Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator

event_log ip mail migration

Secret key operations

secret_key

Plesk Administrator

Server operations

server

Plesk Administrator

SiteApp operations

siteapp

Plesk Administrator

Spam filtering

spamfilter

Plesk Administrator Plesk Administrator Plesk Administrator

Upload Virtual directory operations

upload virtdir

34

XML Schemas for API RPC Operators

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

v.1.4.1.2
Version 1.4.1.2 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.4.1.2 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client domain_alias Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client

Client template operations Database server operations Desktop operations DNS operations Domain operations

client-template db_server

desktop dns domain

Domain template operations Domain alias operations Event Logging IP operations Mail operations

domain-template

event_log ip mail

XML Schemas for API RPC Operators

35

Migration operations

migration

migration_input.xsd, migration_output.xsd, plesk_migration.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter_input.xsd, spamfilter_output.xsd, plesk_spamfilter.xsd upload_output.xsd virtdir.xsd

Plesk Administrator

Secret key operations

secret_key

Plesk Administrator

Server operations

server

Plesk Administrator

SiteApp operations

siteapp

Plesk Administrator

Spam filtering

spamfilter

Plesk Administrator Plesk Administrator Plesk Administrator

Upload Virtual directory operations

upload virtdir

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

v.1.4.2.0
Version 1.4.2.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.4.2.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations

client-template

36

XML Schemas for API RPC Operators

Database server operations Desktop operations DNS operations Domain operations

db_server

database_input.xsd, database_output.xsd, plesk_db.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd ftpuser.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd maillist.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter.xsd, plesk_spamfilter.xsd upload_output.xsd virtdir.xsd webuser.xsd

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

desktop dns domain

Domain template operations Domain alias operations Event Logging Additional FTP account operations IP operations Mail operations Mailing list operations Migration operations

domain-template domain_alias

Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator

event_log ftp-user ip mail maillist migration

Secret key operations

secret_key

Plesk Administrator

Server operations

server

Plesk Administrator

SiteApp operations

siteapp

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client

Spam filtering Upload Virtual directory operations Web user operations

spamfilter upload virtdir webuser

XML Schemas for API RPC Operators

37

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

v.1.5.0.0
Version 1.5.0.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.5.0.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd descriptor.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations Database server operations

client-template db_server

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator

Descriptor structure Desktop operations DNS operations Domain operations

desktop dns domain

Domain template operations Domain alias operations Event Logging

domain-template domain_alias

event_log

38

XML Schemas for API RPC Operators

Localization operations Log rotation operations Additional FTP account operations IP operations Mail operations Mailing list operations Migration operations

locale log-rotation ftp-user ip mail maillist migration

locale.xsd logrotation.xsd ftpuser.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd maillist.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd session.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter.xsd, plesk_spamfilter.xsd updater.xsd upload_output.xsd virtdir.xsd webuser.xsd

Plesk Administrator Plesk Administrator, Plesk client Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator

Secret key operations

secret_key

Plesk Administrator

Server operations

server

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client

Session management operations SiteApp operations

session siteapp

Spam filtering Updater operations Upload Virtual directory operations Web user operations

spamfilter updater upload virtdir webuser

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

XML Schemas for API RPC Operators

39

v.1.5.1.0
Version 1.5.1.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd (./rpc/1.5.1.0/agent_input.xsd). This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available.

Version 1.5.1.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd descriptor.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd locale.xsd logrotation.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations Database server operations

client-template db_server

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk client

Descriptor structure Desktop operations DNS operations Domain operations

desktop dns domain

Domain template operations Domain alias operations Event Logging Localization operations Log rotation operations

domain-template domain_alias

event_log locale log-rotation

40

XML Schemas for API RPC Operators

Additional FTP account operations IP operations Mail operations Mailing list operations Migration operations

ftp-user ip mail maillist migration

ftpuser.xsd ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd maillist.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd session.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter.xsd, plesk_spamfilter.xsd updater.xsd upload_output.xsd virtdir.xsd webuser.xsd backup.xsd

Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator

Secret key operations

secret_key

Plesk Administrator

Server operations

server

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

Session management operations SiteApp operations

session siteapp

Spam filtering Updater operations Upload Virtual directory operations Web user operations Operations with Plesk backups

spamfilter updater upload virtdir webuser backup-manager

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

XML Schemas for API RPC Operators

41

v.1.5.2.0
Version 1.5.2.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available. Version 1.5.2.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd descriptor.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd locale.xsd logrotation.xsd ftpuser.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations Database server operations

client-template db_server

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk client Plesk Administrator, Plesk Client

Descriptor structure Desktop operations DNS operations Domain operations

desktop dns domain

Domain template operations Domain alias operations Event Logging Localization operations Log rotation operations Additional FTP account operations

domain-template domain_alias

event_log locale log-rotation ftp-user

42

XML Schemas for API RPC Operators

IP operations Mail operations Mailing list operations Migration operations

ip mail maillist migration

ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd maillist.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd protected_dir.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd session.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter.xsd, plesk_spamfilter.xsd subdomain.xsd ui_input.xsd, ui_output.xsd, plesk_custom_button.xsd updater.xsd upload_output.xsd virtdir.xsd webuser.xsd backup.xsd

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator

Protected directory operations Secret key operations

protected_dir secret_key

Server operations

server

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

Session management operations SiteApp operations

session siteapp

Spam filtering Subdomain operations User interface operations Updater operations Upload Virtual directory operations Web user operations Operations with Plesk backups

spamfilter subdomain ui updater upload virtdir webuser backup-manager

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

XML Schemas for API RPC Operators

43

v.1.5.2.1
Version 1.5.2.1 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available. Version 1.5.2.1 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd descriptor.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd locale.xsd logrotation.xsd ftpuser.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations Database server operations

client-template db_server

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk client Plesk Administrator, Plesk Client

Descriptor structure Desktop operations DNS operations Domain operations

desktop dns domain

Domain template operations Domain alias operations Event Logging Localization operations Log rotation operations Additional FTP account operations

domain-template domain_alias

event_log locale log-rotation ftp-user

44

XML Schemas for API RPC Operators

IP operations Mail operations Mailing list operations Migration operations

ip mail maillist migration

ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd maillist.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd protected_dir.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd session.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter.xsd, plesk_spamfilter.xsd subdomain.xsd ui_input.xsd, ui_output.xsd, plesk_custom_button.xsd updater.xsd upload_output.xsd virtdir.xsd

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator

Protected directory operations Secret key operations

protected_dir secret_key

Server operations

server

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

Session management operations SiteApp operations

session siteapp

Spam filtering Subdomain operations User interface operations Updater operations Upload Virtual directory operations Web user operations Operations with Plesk backups

spamfilter subdomain ui updater upload virtdir webuser backup-manager

webuser.xsd backup.xsd

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

XML Schemas for API RPC Operators

45

v.1.6.0.0
Version 1.6.0.0 of Plesk XML API has a two-level structure as follows: An entry point to the input XML schemas is agent_input.xsd. This file references all lower-level input schemas available. An entry point to the output XML schemas is agent_output.xsd. This file references all lower-level output schemas available. Version 1.6.0.0 of Plesk XML API supports operations on the following Plesk objects:
SUPPORTED OPERATION Certificate operations Client operations OPERATOR certificate client SCHEMAS certificate_input.xsd, certificate_output.xsd client_input.xsd, client_output.xsd, plesk_client.xsd client_template.xsd database_input.xsd, database_output.xsd, plesk_db.xsd descriptor.xsd desktop.xsd dns_input.xsd, dns_output.xsd, plesk_dns.xsd domain_input.xsd, domain_output.xsd, plesk_domain.xsd domain_template.xsd domainalias_input.xsd, domainalias_output.xsd, plesk_domainalias.xsd event_log_input.xsd, event_log_output.xsd locale.xsd logrotation.xsd ftpuser.xsd AVAILABLE TO Plesk Administrator Plesk Administrator Plesk Administrator

Client template operations Database server operations

client-template db_server

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk client Plesk Administrator, Plesk Client

Descriptor structure Desktop operations DNS operations Domain operations

desktop dns domain

Domain template operations Domain alias operations Event Logging Localization operations Log rotation operations Additional FTP account operations

domain-template domain_alias

event_log locale log-rotation ftp-user

46

XML Schemas for API RPC Operators

IP operations Mail operations Mailing list operations Migration operations

ip mail maillist migration

ip_input.xsd, ip_output.xsd mail_input.xsd, mail_output.xsd, plesk_mailname.xsd maillist.xsd migration_input.xsd, migration_output.xsd, plesk_migration.xsd protected_dir.xsd secret_key_input.xsd, secret_key_output.xsd, plesk_secretkeys.xsd server_input.xsd, server_output.xsd, plesk_server.xsd session.xsd siteapp_input.xsd, siteapp_output.xsd, plesk_siteapp.xsd spamfilter.xsd, plesk_spamfilter.xsd subdomain.xsd ui_input.xsd, ui_output.xsd, plesk_custom_button.xsd updater.xsd upload_output.xsd virtdir.xsd

Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator

Protected directory operations Secret key operations

protected_dir secret_key

Server operations

server

Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client Plesk Administrator, Plesk Client

Session management operations SiteApp operations

session siteapp

Spam filtering Subdomain operations User interface operations Updater operations Upload Virtual directory operations Web user operations Operations with Plesk backups Operations with Plesk resellers Operations with Plesk reseller templates

spamfilter subdomain ui updater upload virtdir webuser backup-manager reseller reseller-template

webuser.xsd backup.xsd reseller.xsd reseller_template.xsd

Simple and commonly used types are provided in schemas common.xsd and plesk_common.xsd.

CHAPTER 5

Representation of Object Descriptor


Every object descriptor is composed of a set of property descriptors and correlation between properties of the object. Its graphical representation is as follows:

The descriptor node is required. It specifies object descriptor. Data type: ObjectDescriptor (descriptor.xsd). The property node is required. It specifies one or more property descriptors. For details, refer to the Descriptor of Property (on page 48) section. Data type: PropertyDescriptor (descriptor.xsd). The bind node is optional. It defines correlation between properties of the object. For details, refer to the Bind Parameters (on page 55) section. Data type: PropertyDescriptor (descriptor.xsd).

Before you start using descriptors, read more about descriptor filtering issues in the Filters of Descriptors (on page 48) section. For more info on descriptors, refer to the Descriptors Overview section of the Programming Guide.

In this chapter:
Filters of Descriptors ......................................................................................... 48 Property Descriptor ........................................................................................... 48 Bind Parameters ............................................................................................... 55

48

Representation of Object Descriptor

Filters of Descriptors

Filters used by descriptors differs from filters used by operators. There are client-level and domain-level filters for object descriptors. Client-level filters can specify a client by ID or login name. Domain-level filters can specify a domain by name, ID, or they can specify multiple domains belonging to a specified client by client ID or login name. If the filter node is not blank (<filter/>) the server will return descriptor for an object, specified by filtering rule parameters. In this case there will be filter-id and id nodes in the response packet. If the filter node is blank the server will return the server-level descriptor for a specified object. In this case there will not be filter-id and id nodes in the response packet. A single filter node cannot contain filtering parameters presented by different nodes in XML schema, but can contain multiple filtering parameters presented by the same node in XML schema. For details on descriptors, refer to the Descriptors section of the Programming Guide.

Representation of Object Descriptor

49

Property Descriptor
Property descriptor is comprised of parameters that specify an object property. Its graphical representation is as follows:

The property node is required. It specifies a property descriptor. Data type: PropertyDescriptor (descriptor.xsd). The name node is required. It specifies identifier of the property. Data type: string. The type node is required. It specifies a type of property value. Data type: string. Allowed values: string | password | int | uint | float | boolean | bytes | date Where uint is an unsigned integer. Date is stored in timestamp format. In 'bytes' type -1 (value) = UNLIMITED

The enum node is optional. It specifies values of the property in case the property has limited set of values. Data type: EnumElementType (descriptor.xsd). The value node is required if the enum node is specified. It defines a value of the property. Data type: string.

50

Representation of Object Descriptor

The label node is optional. It specifies brief explanation of the property value in Plesk GUI. This value should be equal to locale key name of the property. To retrieve locale key value, use the locale operator. Data type: string. The hint value is optional. It specifies the hint that can be seen if you point cursor on the property label in Plesk GUI. Data type: string.

The default-value node is optional. It specifies default value of the property. Data type: none. The writable-by node is optional. It specifies users who can edit the property. Data type: sting. Allowed values: none | admin | client | domain-admin. The label node is optional. It specifies brief explanation of the property in Plesk GUI. This value should be equal to locale key name of the property. To retrieve locale key value, use the locale operator. Data type: string. The hint node is optional. It specifies hint that can be seen if you point cursor on the property label in Plesk GUI. Data type: string. The extension node is optional. It defines data specific for the object. For details, refer to the Extension of Permissions Descriptor (on page 51), Extension of Hosting Settings Descriptor (on page 51) and Extension of Limits Descriptor (see page 53) sections. Data type: any.

Samples The following property descriptor specifies FTP quota.


<property> <name>ftp_quota</name> <type>int</type> <default>-1</default> <writable-by>admin</writable-by> </property>

The following property descriptor specifies PHP support.


<property> <name>php</name> <type>boolean</type> <default>1</default> <writable-by>admin</writable-by> <writable-by>client</writable-by> <writable-by>domain-admin</writable-by> </property>

In this section:
Extension of Permissions Descriptor ................................................................. 51 Extension of Hosting Settings Descriptor........................................................... 51 Extension of Limits Descriptor ........................................................................... 53

Representation of Object Descriptor

51

Extension of Permissions Descriptor


This extension is used to define correlations between types of users and permissions. If you send request packet containing the get-permission-descriptor operation, the respond from the server will contain permission level in the level node nested into the extension node. The graphical representation of the construction is as follows:

This node can be empty, or contain one of the following values: client. The parameter is visible to clients. domain. The parameter is visible to domain administrators. mail. The parameter is visible to mail account users.

Note: You can specify multiple service parameters in one extension node. Extension node sample
<packet> <property> <name>manage_virusfilter</name> <type>boolean</type> <default-value>false</default-value> <writable-by>admin</writable-by> <label>cl_perm__manage_virusfilter</label> <extension> <level>client</level> <level>domain</level> <level>mail</level> </extension> </property>

For details on permissions, refer to the Limits and Permissions (on page 70) (client's settings), or Limits, Permissions and Hosting Settings (on page 397) (domain and domain administrator's settings) sections.

52

Representation of Object Descriptor

Extension of Hosting Settings Descriptor


This extension is used to define visible properties on managing Plesk hosted objects. If you send a request packet containing the get-physical-hosting-descriptor operation, the service node, or one or several level nodes in preassigned order nested into the extension node will set if a property is visible when you manage a specified object. The extension node of physical hosting property can be represented graphically as follows:

The service node is required if the property is a service. It specifies if the service is a hosting property of a managed object defined by a child node. The node can contain several or all of the following child nodes in the preassigned order: the domain node specifies if the property is visible when managing domains. the subdomain node specifies if the property is visible when managing typical subdomains. the webuser node specifies if the property is visible when managing web users. the subdomain-on-subfolder specifies if the property is visible when managing subdomains on subfolder.

The level node is required if the property is not a service. Supported since the protocol v.1.5.2.0. It specifies if the property is visible when managing an object. The level node can have one of the following values: domain. The property is visible when managing domains. subdomain. The property is visible when managing typical subdomains. subdomain-on-subfolder. The property is visible when managing subdomains on subfolder.

Representation of Object Descriptor

53

This part of a physical hosting descriptor represents the service property asp visible when managing domains, subdomains and web users in Plesk for Unix.
<property> <name>asp</name> <type>boolean</type> <writable-by>admin</writable-by> <label>__asp_unix_support</label> <extension> <service> <domain>1</domain> <subdomain>1</subdomain> <webuser>1</webuser> </service> </extension> </property>

This part of a physical hosting descriptor represents the non-service property fp visible when managing domains, and the non-service property ftp_quota visible when managing domains and subdomains in Plesk for Unix.
<property> <name>fp</name> <type>boolean</type> <writable-by>none</writable-by> <label>__fp_unix_support</label> <extension> <level>domain</level> </extension> </property> <property> <name>ftp_quota</name> <type>bytes</type> <writable-by>none</writable-by> <label>__hard_disk_quota</label> <extension> <level>domain</level> <level>subdomain</level> </extension> </property>

For details on hosting settings, refer to the Limits, Permissions and Hosting Settings (on page 397) section.

54

Representation of Object Descriptor

Extension of Limits Descriptor

Number of limits have values equal to users of different access levels. For instance, mailbox quota is a shared parameter, because it's value is equal both for a client and for domain administrator. Graphically, the extension node can be represented in the following way:

The shared node is required. Data type: boolean.

Extension node sample


<property> <name>max_subdom</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_subdom</label> <extension> <shared>false</shared> </extension> </property>

For details on limits, refer to the Limits and Permissions (on page 70) (client's settings), or Limits, Permissions and Hosting Settings (on page 397) (domain and domain administrator's settings) sections.

Representation of Object Descriptor

55

Bind Parameters
Bind parameters hold correlation between properties of the object. Typical bind parameter has the following graphical representation:

The bind node is optional. It specifies the bind parameter. Data type: BindType (descriptor.xsd). If it is specified, it contains the following parameters: The ref node is required. It specifies name of a property to be bound with other properties. The relevant node is optional. It contains rules defining dependence of the property on another. A depended property can be editable only if the "master" property's value (or read-only indicator) is equal to a specified value. Data type: RelevantType (descriptor.xsd). If it is specified, it contains the following parameters: The name node is required. It specifies name of another property this property will depend on. Data type: string. The value node is required. It specifies value of another property this property will depend on. Data type: string. The read-only node is required. It specifies if the property (defined in ref node) will be editable on fulfilling conditions defined in the relevant node. Data type: boolean.

The read-only node is required. It defines if the property is editable for users. Data type: boolean.

Note: read-only is of higher priority than writable-by.

56

Representation of Object Descriptor

Remarks Multiple bind nodes for a single property descriptor are treated as logical disjunction of correlations. Multiple relevant nodes are treated as logical conjunction of the rules. This rule tells to make PHP ISAPI support editable only if PHP support is editable and checked.
<bind> <ref>php_isapi</ref> <relevant> <id>php</id> <read-only>0</read-only> </relevant> <relevant> <id>php</id> <value>1</value > </relevant> <read-only>0</read-only> </bind>

CHAPTER 6

Supported Operations
This chapter can serve as a guide on how each Plesk object can be managed programmatically via Plesk API RPC protocol. Each section is devoted to a particular object or range of objects. For your convenience the sections are arranged in alphabetical order. Each section, at first, lists all operations on the objects in focus that are supported by API RPC, then each operation is considered in detail with XML code samples. The detailed description touches upon the structure of the request and response packets.

In this chapter:
Managing Client Accounts ................................................................................. 58 Managing Client Templates ............................................................................... 135 Managing Database Servers ............................................................................. 161 Managing Databases ........................................................................................ 202 Managing Desktop Presets ............................................................................... 251 Managing DNS .................................................................................................. 276 Managing Domain Accounts.............................................................................. 377 Managing Domain Aliases ................................................................................. 487 Managing Domain Templates ............................................................................ 516 Managing FTP Accounts ................................................................................... 555 Managing IP Addresses .................................................................................... 587 Managing Locales ............................................................................................. 605 Managing Log Rotation on Domain ................................................................... 640 Managing Mail on Domain Level ....................................................................... 673 Managing Mailing Lists ...................................................................................... 728 Managing Plesk Backups .................................................................................. 789 Managing Plesk Server ..................................................................................... 842 Managing Plesk Updates................................................................................... 905 Managing Protected Directories ........................................................................ 922 Managing Reseller Accounts ............................................................................. 970 Managing Reseller Templates ........................................................................... 1030 Managing Secret Keys ...................................................................................... 1050 Managing Sessions ........................................................................................... 1065 Managing Web Applications .............................................................................. 1072 Managing Spam Filtering Service ...................................................................... 1111 Managing SSL Certificates ................................................................................ 1160 Managing SSO Service ..................................................................................... 1178 Managing Subdomains...................................................................................... 1218 Managing User Interface ................................................................................... 1245 Managing Virtual Directories ............................................................................. 1267 Managing Web Users ........................................................................................ 1284 Migrating Domain And Client Accounts ............................................................. 1325 Retrieving Action Log Data ................................................................................ 1360 Uploading Files to Server .................................................................................. 1368

58

Supported Operations

Managing Client Accounts


Operator: <client> XML Schema: client_input.xsd, client_output.xsd, plesk_client.xsd Plesk version: all versions API RPC version: all versions Plesk user: Plesk Administrator, Plesk reseller (since protocol version 1.6.0.0) Description The hierarchy of Plesk users includes resellers, clients, domain administrators, and email users (enumerated in the descending level order). Creating a Plesk Client is equivalent to creating a special client account. This operation is allowed to Plesk resellers (since protocol version 1.6.0.0) and Plesk Administrator. Client account presents a set of Plesk client personal data and a collection of various settings. These settings are as follows: Limits on use of Plesk resources Access permissions IP pool settings Template settings Ownership settings. Since protocol version 1.6.0.0, each client account has an owner (Plesk Administrator or a Plesk Reseller). Owner of an existing client account can be changed. Plesk Administrator can upgrade his client accounts to reseller accounts.

Once created, a client account is allotted a portion of Plesk server disk space and other Plesk resources. A client account can be created with a unique collection of settings, or this can be done using a client template (a special object that holds a collection of predefined settings). To learn more about client templates, refer to section Managing Client Templates (see page 135). In turn, Plesk client can create and manage domains and user accounts that share the disk space of the 'parent' client account.

Supported Operations

59

Supported operations

ADD (see page 81) creates new client account to Plesk database. GET (see page 87) retrieves the information about the specified client account(s) from Plesk database. DEL (see page 95) deletes the specified client account(s) from Plesk database. SET (see page 100) updates/ modifies certain information about the specified client account(s) in Plesk database. IPPOOL_ADD_IP (see page 107) adds IP addresses to the clients IP pool. IPPOOL_DEL_IP (see page 109) removes IP addresses from the clients IP pool. CFORM_BUTTONS_LIST (see page 112) retrieves the list of buttons displayed on the client's home page. GET-LIMIT-DESCRIPTOR (on page 119) retrieves client limits descriptors. GET-PERMISSION-DESCRIPTOR (on page 125) retrieves client permissions descriptors. CONVERT-TO-RESELLER (on page 128) upgrades client accounts to reseller accounts. The feature is supported since protocol version 1.6.0.0.

60

Supported Operations

CHANGE-OWNER (on page 132) assigns a new owner to a client account. The feature is supported since protocol version 1.6.0.0.

In this section:
Filtering Issues .................................................................................................. 60 Client Settings ................................................................................................... 63 Creating Client Account ..................................................................................... 81 Getting Information About Client Accounts ........................................................ 87 Deleting Client Accounts ................................................................................... 95 Setting Client Account Properties ...................................................................... 100 Adding IP Addresses to Clients IP Pool ............................................................ 107 Removing IP Addresses from the Clients IP Pool ............................................. 109 Listing Buttons Displayed on the Clients Page in Control Panel........................ 112 Retrieving Descriptor of Limits ........................................................................... 119 Retrieving Descriptor of Permissions ................................................................. 125 Upgrading Client Account to Reseller Account .................................................. 128 Changing Client Account Owner........................................................................ 132

Filtering Issues
Filtering is the way the request XML packet indicates the object (one or several client accounts) to which the operation will be applied. Parameters nested in the filter node are called filtering rule. The filter node is presented by the ClientSelectionFilterType complex type (client_input.xsd). Its graphical representation is as follows:

Supported Operations

61

The id node is optional. It specifies ID of a client account. Data type: integer. The login node is optional. It specifies login name of a client account. Data type: string. The owner-id node is optional. It specifies ID of a client account owner. Data type: integer. This node is supported since protocol version 1.6.0.0. The owner-login node is optional. It specifies login name of a client account owner. Data type: string. This node is supported since protocol version 1.6.0.0. The guid node is optional. It specifies the GUID of a client account. This node is supported since protocol version 1.6.0.0. For details on GUIDs, refer to the API RPC Protocol > GUIDs Overview section of Plesk API RPC Developer's Guide. Data type: string.

The following packet removes client accounts which belong to Plesk Administrator:
<packet version=1.6.0.0> <client> <del> <filter> <owner-login>admin</owner-login> </filter> </del> </client> </packet>

The following packet deletes three client accounts specified by id:


<packet version=1.4.2.0> <client> <del> <filter> <id>124</id> <id>125</id> <id>127</id> </filter> </del> </client> </packet>

The following packet is identical to the previous one except that it specifies client accounts by name:
<packet version=1.4.2.0> <client> <del> <filter> <login>JaneDoe</login> <login>RRoe</login> <login>JohnDoe</login> </filter> </del> </client> </packet>

62

Supported Operations

The following packet is invalid as both the id and the login nodes are used in the same filter:
<packet version=1.4.2.0> <client> <del> <filter> <login>JaneDoe</login> <id>125</id> <login>JohnDoe</login> </filter> </del> </client> </packet>

To fix this problem, use two different <del> sections:


<packet version=1.4.2.0> <client> <del> <filter> <login>JaneDoe</login> <login>JohnDoe</login> </filter> </del> <del> <filter> <id>125</id> </filter> </del> </client> </packet>

Supported Operations

63

Client Settings
This section describes a collection of client account settings. These settings can be defined when creating a client account or later, and retrieved from Plesk database as well. These settings are as follows: General Client Account settings (see page 63) Limits (on page 70) on use of Plesk resources set for the client account Plesk client permissions (on page 70)

The above settings can also be read from Plesk database along with IP pool settings (see page 79) and statistics (see page 80) on use of various Plesk resources by the given Plesk client.

In this section:
General Client Account Settings ........................................................................ 63 Limits and Permissions ..................................................................................... 70 IP Pool Settings................................................................................................. 79 Statistics............................................................................................................ 80

General Client Account Settings


General client account settings are specified by three data types as follows: type clientAddGenInfo (see page 64) - used when creating the client account with the add operation type clientGetGenInfo (see page 67) - used when retrieving the general information from Plesk database using the get operation type clientSetGenInfo (see page 69) - used when updating the client account using the set operation

In this section:
Type clientAddGenInfo ......................................................................................64 Type clientGetGenInfo .......................................................................................67 Type clientSetGenInfo .......................................................................................69

64

Supported Operations

Type clientAddGenInfo
When creating the client account, the general client account information is specified by complex type clientAddGenInfo (plesk_client.xsd). It is structured as follows:

The cname node is optional. Specifies the company name. Data type: string (0 to 60 characters long).

Supported Operations

65

The pname node is required. Specifies the personal name of the customer who owns the client account. Data type: string (1 to 60 characters long). The login node is required. Specifies the login name of the client account. Data type: string (1 to 60 characters long). The passwd node is required. Specifies the password of the client account. Data type: string (5 to 14 characters long) . The status node is optional. Specifies the current status of the client account. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled_by admin) | 4 (under backup/restore) | 256 (expired). Only status values 0 and 16 can be set up. The phone node is optional. Specifies the phone number of the client account owner. Data type: string (0 to 30 characters long). The fax node is optional. Specifies the fax number of the client account owner. Data type: string (0 to 30 characters long). The email node is optional. Specifies the email address of the client account owner. Data type: string (0 to 255 characters long). The address node is optional. Specifies the postal address of the client account owner. Data type: string (0 to 255 characters long). The city node is optional. Specifies the city of the client account owner. Data type: string (0 to 50 characters long). The state node is optional. Specifies the US state of the client account owner (should be specified for US citizens only). Data type: string (0 to 50 characters long). The pcode node is optional. Specifies the zip code of the client account owner (specified for US citizens only). Data type: string (0 to 10 characters long). The country node is optional. Specifies the 2-character country code of the client account owner (US for United States, CA for Canada, etc.). Data type: string (2 characters long). The locale node is optional. Specifies the locale used on the client account. Data type: string. Default value: en-US. Note: In API RPC v.1.5.0.0 and later, use four-letter locale names (RFC 1766). In API RPC v.1.4.2.0 and earlier versions, you can also use two-letter locale names. If you specify two-letter locale name in a request packet, and request packet protocol is API RPC v.1.5.0.0 or later, you will receive the error (error code 1019). If you use API RPC v.1.4.2.0 or earlier versions, the operations will be successfully processed.

The owner-id node is optional. It specifies the ID of a client account owner. Data type: integer. The node is supported since protocol version 1.6.0.0. The owner-login node is optional. It specifies the login name of a client account owner. If the client account owner is Plesk Administrator, specify the admin login name. Data type: string. The node is supported since protocol version 1.6.0.0. Note: If the information about owner is omitted, the client account belongs to the user who issued the request.

66

Supported Operations

The following packet creates a client account and defines the general settings for it:
<packet version="1.6.0.0"> <client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>John Doe</pname> <login>JDoe</login> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>JDoe@example.com</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> <owner-id>3</owner-id> </gen_info> </add> </client> </packet>

Supported Operations

67

Type clientGetGenInfo
When getting the general client account information, complex type clientGetGenInfo (plesk_client.xsd) is used in the response get packet. It is structured as follows (reduced version):

The cr_date node is required. It specifies the date when the specified client account was created. Data type: date. The cname node is required. Specifies the company name. Data type: string (1 to 60 characters long). The pname node is required. Specifies the personal name of the customer who owns the client account. Data type: string (1 to 60 characters long). The login node is required. Specifies the login name of the client account. Data type: string (1 to 20 characters long). The status node is required. Specifies the current status of the client account. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled_by admin) | 4 (under backup/restore) | 256 (expired). Default value: 0.

68

Supported Operations

The phone node is required. Specifies the phone number of the client account owner. Data type: string (0 to 30 characters long). The fax node is required. Specifies the fax number of the client account owner. Data type: string (0 to 30 characters long). The email node is required. Specifies the email address of the client account owner. Data type: string (0 to 255 characters long). The address node is required. Specifies the postal address of the client account owner. Data type: string (0 to 255 characters long). The city node is required. Specifies the city of the client account owner. Data type: string (0 to 50 characters long). The state node is required. Specifies the US state of the client account owner (specified for US citizens only). Data type: string (0 to 50 characters long). The pcode node is required. Specifies the zip code of the client account owner (specified for US citizens only). Data type: string (0 to 10 characters long). The country node is required. Specifies the 2-character country code of the client account owner (US for United States, CA for Canada, etc.). Data type: string (2 characters long). The locale node is required. Specifies the locale used on the client account. Data type: string. Default value: en.

Note: In API RPC v.1.5.0.0 and later, the four-letter locale name is always returned. The password node is optional. Specifies the client account password. Data type: string. Deprecated in API RPC v.1.4.2.0. The password_type node is optional. Specifies the type of the client account password. Data type: string. Allowed values: crypt | plain. The passwd node is optional. Specifies the client account password. Data type: string. Obsolete, used by API RPC 1.3.2 and earlier. The guid node is optional. It contains the client GUID. This node is supported in API RPC 1.5.2.0 and later versions. For details on GUIDs, refer to the GUIDs Overview section of the API RPC Developer Guide. Data type: string. The owner-id node is optional. It holds the identifier of the client owner (reseller or Plesk administrator). Data type: integer. This node is supported in API RPC v.1.6.0.0 and later.

Supported Operations

69

Type clientSetGenInfo
When setting the general client account information, complex type clientSetGenInfo (plesk_client.xsd) is used in the response set packet. It is structured as follows:

The cname node is optional. It specifies the company name. Data type: string (1 to 60 characters long). The pname node is optional. It specifies the personal name of the customer who owns the client account. Data type: string (1 to 60 characters long). The login node is optional. It specifies the login name of the client account. Data type: string (1 to 20 characters long). The passwd node is optional. It specifies the client account password. Data type: string. The status node is optional. It specifies the current status of the client account. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled_by admin) | 4 (under backup/restore) | 256 (expired). Default value: 0. Only status values 0 and 16 can be set up. The phone node is optional. It specifies the phone number of the client account owner. Data type: string (0 to 30 characters long).

70

Supported Operations

The fax node is optional. It specifies the fax number of the client account owner. Data type: string (0 to 30 characters long). The email node is optional. It specifies the email address of the client account owner. Data type: string (0 to 255 characters long). The address node is optional. It specifies the postal address of the client account owner. Data type: string (0 to 255 characters long). The city node is optional. It specifies the city of the client account owner. Data type: string (0 to 50 characters long). The state node is optional. It specifies the US state of the client account owner (specified for US citizens only). Data type: string (0 to 50 characters long). The pcode node is optional. It specifies the zip code of the client account owner (specified for US citizens only). Data type: string (0 to 10 characters long). The country node is optional. It specifies the 2-character country code of the client account owner (US for United States, CA for Canada, etc.). Data type: string (2 characters long). The locale node is optional. It specifies the locale used on the client account. Data type: string. Default value: en-US.

Note: In API RPC v.1.5.0.0 and later, use four-letter locale names (RFC 1766). In API RPC v.1.4.2.0 and earlier versions, you can also use two-letter locale names. If you specify two-letter locale name in a request packet, and request packet protocol is API RPC v.1.5.0.0 or later, you will receive the error (error code 1019). If you use API RPC v.1.4.2.0 or earlier versions, the operations will be successfully processed. The guid node is optional. If specified, the new GUID is assigned to the client. This node is supported in API RPC 1.5.2.0 and later versions.For details on GUIDs, refer to the GUIDs Overview section of the API RPC Developer's Guide. Data type: boolean.

Limits and Permissions


This section contains limits and permissions settings for client accounts. Starting from API RPC 1.5.0.0 you can manage the settings using descriptors. For details on descriptors, refer to the Presentation of Object Descriptor (on page 47) section in API Reference and the Descriptors section in the Programming Guide.

In this section:
API RPC 1.4.2.0 and Earlier Versions ............................................................... 71 API RPC 1.5.0.0 and Later Versions ................................................................. 77

Supported Operations

71

API RPC 1.4.2.0 and Earlier Versions


This section contains limits and permissions settings of a client account, that are available in API RPC v.1.4.2.0 and earlier.

In this section:
Limits................................................................................................................. 71 Permissions....................................................................................................... 74

Limits
The limits on use of Plesk resources are defined by complex type clientLimits (plesk_client.xsd). It is structured as follows:

72

Supported Operations

The max_webapps node is optional. Specifies the maximum number of Tomcat web applications available for the client. Data type: string. The max_maillists node is optional. Specifies the maximum number of mailing lists available for the client. Data type: string. The max_resp node is optional. Specifies the maximum number of email autoresponders available for the client. Data type: string. The max_mg node is optional. Specifies the maximum number of mail groups available for the client. Data type: string. The max_redir node is optional. Specifies the maximum number of redirects available for the client. Data type: string. The mbox_quota node is optional. Specifies the maximum mail box size (in bytes) allowed for the client. Data type: string. The max_box node is optional. Specifies the maximum number of mailboxes allowed for the client. Data type: string. The max_db node is optional. Specifies the maximum number of MySQL databases available for the client. Data type: string. The max_wu node is optional. Specifies the maximum quantity of web users allowed for the client. Data type: string. The max_traffic node is optional. Specifies the limit (in bytes) on the traffic for the client. Data type: string. The disk_space node is optional. Specifies the limit on disk space (in bytes) for the client. Data type: string. The max_subdom node is optional. Specifies the maximum number of subdomains available for the client. Data type: string. The max_dom node is optional. Specifies the limit on the number of domains for the client. Data type: string. The expiration node is optional. Specifies the validity period of the client account in the UNIX timestamp format. Data type: string. The total_mboxes_quota node is optional. Specifies the total size of all mailboxes (in bytes) allowed for the client. Data type: string. Makes sense for Plesk for Windows only. The mysql_dbase_space node is optional. Specifies the maximum disk space (in bytes) occupied by all MySQL databases belonging to the client. Data type: string. Makes sense for Plesk for Windows only. The mssql_dbase_space node is optional. Specifies the maximum disk space (in bytes) occupied by all Microsoft SQL databases belonging to the client. Data type: string. Makes sense for Plesk for Windows only. The max_mssql_db node is optional. Specifies the maximum number of Microsoft SQL databases available for the client. Data type: string. Makes sense for Plesk for Windows only. The max_iis_app_pools node is optional. Specifies the maximum number of IIS application pools available for the client. Data type: string. Makes sense for Plesk for Windows only. The max_shared_ssl_links node is optional. Specifies the maximum number of shared SSL links available for the client. Data type: string. Makes sense for Plesk for Windows only.

Supported Operations

73

The max_subftp_users node is optional. Specifies the maximum number of additional FTP accounts. Data type: integer. Supported in version 1.4.1.0 and higher. Makes sense for Plesk for Windows only. The max_fpse_users node is optional. Specifies the maximum number of additional Microsoft FrontPage accounts. Data type: integer. Supported in version 1.4.1.0 and higher. Makes sense for Plesk for Windows only. The max_dom_aliases node is optional. Specifies the maximum number of domain aliases allowed for the Plesk client just created. Data type: integer. The max_odbc node is optional. Specifies the maximum number of ODBC connections allowed for the Plesk client just created. Data type: integer. Makes sense for Plesk for Windows only. The feature is supported by API RPC 1.4.2.0 and later.

The following packet creates a client account and sets the limits for it:
<packet version="1.4.2.0"> <client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@logicsoft.net</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> </gen_info> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> </add> </client> </packet>

74

Supported Operations

Permissions
Client permissions are presented by complex type clientPerms (plesk_client_xsd). It is structured as follows:

The create_domains node is optional. It allows/disallows the client to create domains. Data type: Boolean. The manage_phosting node is optional. It allows/disallows the client to manage physical hosting. Data type: Boolean. The manage_quota node is optional. It allows/disallows the client to change the hard disk limit. Data type: Boolean. The manage_subdomains node is optional. It allows/disallows the client to manage subdomains. Data type: Boolean.

Supported Operations

75

The manage_not_chroot_shell node is optional. It allows/disallows the client to manage shell without changing the mount point of the UNIX root. Data type: Boolean. The change_limits node is optional. It allows/disallows the client to change the domain limits. Data type: Boolean. The manage_dns node is optional. It allows/disallows the client to manage DNS settings. Data type: Boolean. The manage_log node is optional. It allows/disallows the client to manage log rotation. Data type: Boolean. The manage_crontab node is optional. It allows/disallows the client to manage the task scheduler. Data type: Boolean. The manage_anonftp node is optional. It allows/disallows the client to manage Anonymous FTP. Data type: Boolean. The manage_webapps node is optional. It allows/disallows the client to manage Tomcat web applications. Data type: Boolean. The manage_sh_access node is optional. It allows/disallows the client to use shell access and provide it to users. Data type: Boolean. The manage_maillists node is optional. It allows/disallows the client to manage mailing lists. Data type: Boolean. The manage_drweb node is optional. It allows/disallows the client to manage the DrWeb antivirus program. Data type: Boolean. Available in Plesk 7.1 and higher if DrWeb is supported by the key. The make_dumps node is optional. It allows/disallows the client to use backup/restore functions. Data type: Boolean. The site_builder node is optional. It allows/disallows the client to use SiteBuilder. Data type: Boolean. Available in Plesk 7.1 and higher, not used in Plesk for UNIX beginning with version 8.0. The remote_access_interface node is optional. It allows/disallows the client to use API RPC. Data type: Boolean. Supported in Plesk 7.5.4 for UNIX and later, API RPC 1.3.5 and higher. The manage_performance node is optional. It allows/disallows the client to manage hosting performance. Data type: Boolean. Is used for Plesk for Windows only. The cp_access node is optional. It allows/disallows the client to access Plesk via Control Panel. Data type: Boolean. The manage_domain_aliases node is optional. It allows/disallows the client to manage domain aliases. Is used in Plesk for UNIX only. Data type: Boolean. Supported in API RPC 1.4.0.0 and higher. The manage_iis_app_pool node is optional. It allows/disallows the client to manage IIS application pool. Data type: Boolean. Makes sense for Plesk for Windows only. The dashboard node is optional. It allows/disallows the client to use Plesk Desktop. Data type: Boolean. The stdgui node is optional. It allows/disallows the client to use the standard Plesk GUI. Data type: Boolean. The manage_dashboard node is optional. It allows/disallows the client to manage Plesk Desktop. Data type: Boolean.

76

Supported Operations

The manage_subftp node is optional. It allows/disallows the client to manage additional FTP accounts (with access to the specified domain folders only) created on domains. Data type: Boolean. Supported beginning with version 1.4.1.0 of API RPC. The manage_spamfilter node is optional. It allows/disallows Plesk client to manage spam filter settings. Data type: Boolean. Makes sense for Plesk for UNIX only. The feature is supported by API RPC 1.4.2.0 and later. The allow_local_backups node is optional. It allows/disallows Plesk client to use the local repository for backup/restore functions. Data type: Boolean. Makes sense for Plesk for UNIX only. The feature is supported by API RPC 1.4.2.0 and later. The allow_ftp_backups node is optional. It allows/disallows Plesk client to use the FTP repository for backup/restore functions. Data type: Boolean. Makes sense for Plesk for UNIX only. The feature is supported by API RPC 1.4.2.0 and later.

The following sample packet creates a client account and sets permissions for it:
<packet version="1.4.2.0"> <client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@logicsoft.net</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> </gen_info> <permissions> <create_domains>true</create_domains> <manage_phosting>true</manage_phosting> <manage_quota>false</manage_quota> <manage_subdomains>true</manage_subdomains> <change_limits>true</change_limits> <manage_dns>true</manage_dns> <manage_log>true</manage_log> <manage_anonftp>true</manage_anonftp> <manage_webapps>true</manage_webapps> <manage_sh_access>true</manage_sh_access> <manage_maillists>true</manage_maillists> <make_dumps>true</make_dumps> <remote_access_interface>true</remote_access_interface> <cp_access>true</cp_access> <manage_domain_aliases>true </manage_domain_aliases> </permissions> </add> </client> </packet>

Supported Operations

77

API RPC 1.5.0.0 and Later Versions


This section contains clients limits and permissions settings of a client account, that are available in API RPC v.1.5.0.0 and later.

In this section:
Limits................................................................................................................. 77 Permissions....................................................................................................... 79

Limits
The limits node is presented by clientLimits type (plesk_client.xsd). Note: To manage limits, you should first retrieve limits descriptor (for a specified client), containing names of limits. For details, refer to the Retrieving Descriptor of Limits (on page 119) section. API RPC 1.6.0.0 and Later Versions For protocol version 1.6.0.0 and later, the limits node graphical representation is as follows:

The resource-policy node is optional. It specifies limits policy for a client account. The overuse node is required. It specifies the limits overuse policy for a client account. Data type: string. Allowed values: block | notify | normal.

The limit node is optional. It specifies parameters of a limit. Data type: PleskLimitType (plesk_client.xsd). The name node is required. It specifies a limit name. Data type: sting. The value node is required. It specifies a limit value. Data type: any.

Note: You can specify multiple limit parameters in one limits node.

78

Supported Operations

The following code example sets the limits overuse policy and the maximum databases limit:
<limits> <resource-policy> <overuse>notify</overuse> </resource-policy> <limit> <name>max_db</name> <value>100</value> </limit> </limits>

API RPC 1.5.2.1 and Earlier Versions For protocol version 1.5.2.1 and earlier, graphical representation of the limits node is as follows:

The limit node is required. It specifies parameters of a limit. Data type: PleskLimitType (plesk_client.xsd). The name node is required. It specifies a limit name. Data type: sting. The value node is required. It specifies a limit value. Data type: any.

Note: You can specify multiple limit parameters in one limits node. The following code example sets the maximum databases limit:
<limits> <limit> <name>max_db</name> <value>100</value> </limit> </limits>

Supported Operations

79

Permissions
The permissions node is presented by clientPerms type (plesk_client.xsd), and its graphical representation is as follows:

The permission node is required. It specifies parameters of a permission. Data type: PleskPermissionType (plesk_client.xsd). The name node is required. It specifies a permission name. Data type: sting. The value node is required. It specifies a permission value. Data type: any.

Note: You can specify multiple permission parameters in one permissions node. The following code enables to create domain accounts:
<permissions> <permission> <name>create_domains</name> <value>true</value> </permission> </permissions>

Note: To manage permissions, you should first retrieve permissions descriptor (for a specified client), containing names of permissions. For details, refer to the Retrieving Descriptor of Permissions (on page 125) section.

IP Pool Settings
Every client account has its own pool of IP addresses. It is presented in XML packets by node ippool of type ipPoolType (plesk_client.xsd). This node is structured as follows:

The ip-address node is optional. It specifies a single IP address currently available in the IP pool of the Plesk client. Data type: ip_address (string).

80

Supported Operations

Statistics
The statistics requested from Plesk database for a certain Plesk client is returned in the stat node of type clientStatType (plesk_client.xsd). This node is structured as follows:

The active_domains node is required. It specifies the number of active domains created by Plesk Client. Data type: unsignedInt. Default value: 0. The subdomains node is required. It specifies the number of sub-domains created by Plesk Client. Data type: unsignedInt. Default value: 0. The disk_space node is required. It specifies the amount of disk space occupied by the given Plesk Client. Data type: integer. Default value: 0. The postboxes node is required. It specifies the number of email boxes created by Plesk Client. Data type: unsignedInt. Default value: 0. The redirects node is required. It specifies the number of redirects created by Plesk Client. Data type: unsignedInt. Default value: 0. The mail_groups node is required. It specifies the number of email groups created by Plesk Client. Data type: unsignedInt. Default value: 0. The mail_resps node is required. It specifies the number of automatic response messages created by Plesk Client. Data type: unsignedInt. Default value: 0. The mail_lists node is required. It specifies the number of mailing lists created by Plesk Client. Data type: unsignedInt. Default value: 0.

Supported Operations

81

The web_users node is required. It specifies the number of web users created by Plesk Client. Data type: unsignedInt. Default value: 0. The data_bases node is required. It specifies the number of databases used by Plesk client. Data type: unsignedInt. Default value: 0. The webapps node is required. It specifies the number of Tomcat web applications used by Plesk Client. Data type: unsignedInt. Default value: 0. The traffic node is required. It specifies the amount of traffic (in bytes) spent by Plesk client monthly. Data type: integer. Default value: 0. The traffic_prevday node is required. It specifies the amount of traffic (in bytes) spent by Plesk client during the previous day. Data type: integer. Default value: 0.

Creating Client Account


Client accounts can be created by Plesk Administrator only. Client account presents some general information about Plesk client and a collection of various settings. These settings are as follows: Ownership settings Limits on use of Plesk resources Plesk client access permissions Plesk client IP pool settings Client template on which the client account is based

The general information is always specified when creating a client account, while settings can be specified later. The only exception is a client template. It can be applied only when creating the client account. To learn more about client templates, refer to section Managing Client Templates (see page 135). Note: If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions, a created client account is assigned to Plesk Administrator.

In this section:
Request Packet Structure.................................................................................. 82 Request Samples .............................................................................................. 83 Response Packet Structure ............................................................................... 85 Response Samples ........................................................................................... 86

82

Supported Operations

Request Packet Structure


A request XML packet adding a new client account to Plesk database includes the add operation node:
<packet version=1.4.2.0> <client> <add> </add> </client> </packet>

The add node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). The add node has the following graphics representation:

The gen_info node is required. Specifies the general information about the new client account. Data type: clientAddGenInfo (plesk_client.xsd). See the structure of this node in topic General Client Account Settings (see page 64). The add_packages_to_client_pool is optional. Specifies the list of web application distributions that should be added to the client pool (to be deployed to the client's domains later). Data type: none. See the structure of this node below. The limits node is optional. Specifies the set of limits imposed on Plesk resources accessible to the new client. Data type: clientLimits (plesk_client.xsd). See the structure of this node in the Limits and Permissions (on page 70) topic. The permissions node is optional. Specifies the clients list of permissions for using Plesk resources and managing own services. Data type: clientPerms (plesk_client.xsd). See the structure of this node in the Limits and Permissions (on page 70) topic. The template-id node is optional. Is used to specify the client template if the new client account must be based on any. Data type: integer. The feature is supported in API RPC 1.4.2.0 and later. The template-name node is optional. Is used to specify the client template name if the new client account must be based on any. Data type: string. The feature is supported in API RPC 1.4.2.0 and later.

Supported Operations

83

Note: You can use only templates to which the client account owner has access. For instance, Plesk Administrator can use only shared templates to create client accounts for resellers. The sbnet-user node is optional. Is true if a Sitebuilder user should be created when creating the client template. Data type: Boolean. The feature is supported by Plesk for Windows since API RPC protocol v.1.4.2.0 and by Plesk for Unix since API RPC protocol v.1.5.2.0.

The add_packages_to_client_pool node doesn't have a special data type, it is defined within the add node as follows:

The package_id node is required. It specifies the identifier of the distribution package to be added to the client pool. Data type: integer.

Request Samples
The following packet creates a client account and sets the collection of settings for it:
<packet version="1.4.2.0"> <client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@logicsoft.net</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> </gen_info> </add> </client> </packet>

84

Supported Operations

A client account can be created using a client template. The following packet performs this task:
<packet version="1.4.2.0"> <client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@logicsoft.net</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> </gen_info> <template-name>base_template</template-name> </add> </client> </packet>

Client templates normally define a collection of client settings (limits, permissions, etc), so this packet creates a client account with these settings set already. See the Managing Client Templates (see page 135) section for details. To create multiple client accounts (e.g., using a client template), use a different add operations for each:
<packet version="1.4.2.0"> <client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@logicsoft.net</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> </gen_info> </add> <add>

Supported Operations <gen_info> <cname>TechnoSoft Ltd.</cname> <pname>James Hardy</pname> <login>jhard</login> <passwd>Jk8Dhh6fBB</passwd> <status>0</status> <phone>416 907 3366</phone> <fax>928 752 3377</fax> <email>james@technosoft.net</email> <address>122 Greenroad Valley, Unit 1</address> <city>Toronto</city> <state/> <pcode/> <country>CA</country> </gen_info> <template-name>base_template</template-name> </add> </client> </packet>

85

Response Packet Structure


The add node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested add operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the add operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the add operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the add operation fails. Data type: string. The id node is optional. It is required if the add operation succeeds. Returns the unique identifier of the client account just added to Plesk. Data type: integer.

86

Supported Operations

Response Samples
A response packet received after the client account is created successfully looks as follows:
<packet version=1.4.2.0> <client> <add> <result> <status>ok</status> <id>2435</id> </result> </add> </client> </packet>

If the packet created more than one client account, each create operation will be reported in a separate add node:
<packet version=1.4.2.0> <client> <add> <result> <status>ok</status> <id>2435</id> </result> </add> <add> <result> <status>ok</status> <id>2436</id> </result> </add> </client> </packet>

If the operation fails, the negative response can look as follows:


<packet version=1.4.2.0> <client> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </add> </client> </packet>

In API RPC 1.5.1.0 and later versions, when adding the client with already existing login, the error with error code 1007 occurs. The add sections will follow one another in the order they have been listed in the request packet.

Supported Operations

87

Getting Information About Client Accounts


The get operation is used to retrieve client account settings from Plesk database. These settings are as follows: General information about a Plesk client (owner, name, company, contact data, and so on) Statistics on this Plesk client Limits on use of Plesk resources set for this Plesk client Access permissions set for this Plesk client IP pool settings set for this Plesk client

To retrieve this information, send a request packet with the get operation to Plesk server. Note: If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions, and you request info on all client accounts using get, Plesk will return info on all client accounts, reseller accounts and artificial client account. Plesk user hierarchy will not be retained. Note: If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions, the get operation returns total reseller account statistics. It means that if you request statistics for a reseller who owns client accounts, the total statistics for these client accounts and for the reseller account will be provided (number of subdomains, spent traffic, etc.).

In this section:
Request Packet Structure.................................................................................. 87 Request Samples .............................................................................................. 89 Response Packet Structure ............................................................................... 91 Response Samples ........................................................................................... 93

Request Packet Structure


A request XML packet retrieving information about the client accounts from Plesk database includes the get operation node:
<packet version=1.4.2.0> <client> <get> </get> </client> </packet>

88

Supported Operations

The get node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). The get node has the following graphics representation:

The dataset node is required. It indicates the types of information requested from Plesk database. Data type: clientDatasetType (plesk_client.xsd). The gen_info node is optional. It is used to request for the general client account settings. Data type: none. The stat node is optional. It is used to request statistics on the specified clients. Data type: none. The permissions node is optional. It is used to request permissions set for the specified Plesk clients. For details, refer to the Limits and Permissions (on page 70) section. Data type: none. The limits node is optional. It is used to request the limits set for the specified clients. For details, refer to the Limits and Permissions (on page 70) section. Data type: none. The ippool node is optional. It is used to request the IP pool configuration settings for the specified clients. Data type: none.

Supported Operations

89

Request Samples
To get the information about the client account, specify the packet as follows:
<packet version=1.4.2.0> <client> <get> <filter> <id>1324</id> </filter> <dataset> <gen_info/> <stat/> <permissions/> <limits/> <ippool/> </dataset> </get> </client> </packet>

To send a similar packet for multiple client accounts, use the packet as follows:
<packet version=1.4.2.0> <client> <get> <filter> <id>1324</id> <id>1325</id> </filter> <dataset> <gen_info/> <stat/> <permissions/> <limits/> <ippool/> </dataset> </get> </client> </packet>

90

Supported Operations

You cannot identify multiple client accounts by different parameters (id and login) in the same filter section. The following packet will be invalid:
<packet version=1.4.2.0> <client> <get> <filter> <id>1324</id> <login>technolux</login> </filter> <dataset> <gen_info/> <stat/> <permissions/> <limits/> <ippool/> </dataset> </get> </client> </packet>

To fix this packet, use multiple get sections:


<packet version=1.4.2.0> <client> <get> <filter> <id>1324</id> </filter> <dataset> <gen_info/> <stat/> </dataset> </get> <get> <filter> <login>technolux</login> </filter> <dataset> <permissions/> <limits/> <ippool/> </dataset> </get> </client> </packet>

If you work in the Plesk 9 backward compatibility mode, the following packet will request info on all Plesk reseller and client accounts:
<packet version=1.5.2.0> <client> <get> <filter/> </get> </client> </packet>

Supported Operations

91

Response Packet Structure


The get node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested get operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the get operation fails. Data type: string. The filter-id node is optional. Returns the name or ID of a client depending on a way of client specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. Data type: anySimple. The id node is optional. It is required if the get operation succeeds. Returns the unique identifier of the client account whose data is received from Plesk database. Data type: integer. The data node is optional. It is present if the get operation succeeds. Returns a requested collection of Plesk client settings. Data type: clientData (plesk_client.xsd). See the structure of this node below.

The data node is defined by complex type clientData (plesk_client.xsd). It is structured as follows:

92

Supported Operations

The gen_info node is optional. It returns a collection of general client account settings. Data type: clientGetGenInfo (plesk_client.xsd). See the structure of this node in topic General Client Account Settings (see page 67). The stat node is optional. It returns a the statistics collected on the specified client account. Data type: clientStatType (plesk_client.xsd). See the structure of this node in the Statistics (see page 80) topic. The permissions node is optional. It returns a collection of permissions set for the specified client account. Data type: clientPerms (plesk_client.xsd). For details, refer to the Limits and Permissions (on page 70) section. The limits node is optional. It returns a collection of limits set for the specified client account. Data type: clientLimits (plesk_client.xsd). For details, refer to the Limits and Permissions (on page 70) section. The ippool node is optional. It returns the IP pool configuration settings for the specified client account. Data type: ipPoolType (plesk_client.xsd). See the structure of this node in the IP Pool Settings (see page 79) topic. The sbnet-user node is optional. It indicates whether a SiteBuilder user account was created for the given client account. Data type: Boolean. The feature is supported by Plesk for Windows since API RPC protocol v.1.4.2.0 and by Plesk for Unix since API RPC protocol v.1.5.2.0.

Supported Operations

93

Response Samples
If you use API RPC 1.5.0.0 or later versions, a positive response from the server can look as follows:
<packet version=1.5.0.0> <client> <get> <result> <status>ok</status> <id>1324</id> <data> <limits> <limit> <name>disk_space</name> <value>209715200</value> </limit> <limit> <name>max_dom</name> <value>50</value> </limit> <limit> <name>max_subdom</name> <value>250</value> </limit> <limit> <name>max_webapps</name> <value>30</value> </limit> <limit> <name>max_traffic</name> <value>209715200</value> </limit> <limit> <name>max_db</name> <value>30</value> </limit> <limit> <name>expiration</name> <value>1134616208</value> </limit> </limits> <sbnet-user>false</sbnet-user> </data> </result> </get> </client> </packet>

94

Supported Operations

If you use API RPC 1.4.2.0 or earlier versions, a positive response from the server can look as follows:
<packet version=1.4.2.0> <client> <get> <result> <status>ok</status> <id>1324</id> <data> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> <sbnet-user>false</sbnet-user> </data> </result> </get> </client> </packet>

A negative response can look as follows:


<packet version=1.4.2.0> <client> <get> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1324</id> </result> </get> </client> </packet>

Supported Operations

95

Deleting Client Accounts


The del operation is used to remove the specified client account and all its settings from Plesk database. Note: If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions, and remove a reseller account using del, all client accounts owned by this reseller will also be removed.

In this section:
Request packet Structure .................................................................................. 95 Request Samples .............................................................................................. 96 Response Packet Structure ............................................................................... 98 Response Samples ........................................................................................... 99

Request packet Structure


A request XML packet deleting a client account from Plesk database includes the del operation node:
<packet version=1.4.2.0> <client> <del> </del> </client> </packet>

The del node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). The del node has the following graphics representation:

The filter node is required. It specifies the filtering rule. Data type: clientSelectionFilterType (client_input.xsd). For more information on filters, refer to the Filtering Issues (on page 60) section.

96

Supported Operations

Request Samples
A single request packet can delete a client account or multiple client accounts. If multiple client accounts are deleted, they can be filtered either by id or by login:
<packet version=1.4.2.0> <client> <del> <filter> <id>1324</id> <id>1325</id> </filter> </del> </client> </packet>

Or:
<packet version=1.4.2.0> <client> <del> <filter> <login>technolux</login> <login>advent</login> </filter> </del> </client> </packet>

The following packet is invalid as it uses both id and login in the same filter:
<packet version=1.4.2.0> <client> <del> <filter> <id>1324</id> <login>advent</login> </filter> </del> </client> </packet>

Supported Operations

97

To fix this packet, use multiple del sections:


<packet version=1.4.2.0> <client> <del> <filter> <id>1324</id> </filter> </del> <del> <filter> <login>advent</login> </filter> </del> </client> </packet>

98

Supported Operations

Response Packet Structure


The del node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested del operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the del operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the del operation fails. Data type: string. The filter-id node is optional. Returns the name or ID of a client depending on a way of client specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. Data type: anySimple. The id node is optional. It is required if the del operation succeeds. Returns the unique identifier of the client account just deleted from Plesk. Data type: integer.

Supported Operations

99

Response Samples
After the specified client account has been deleted successfully, the response received from Plesk server can look as follows:
<packet version=1.4.2.0> <client> <del> <result> <status>ok</status> <id>1324</id> </result> </del> </client> </packet>

If multiple client accounts has been deleted successfully, the response packet is as follows:
<packet version=1.4.2.0> <client> <del> <result> <status>ok</status> <id>1324</id> </result> <result> <status>ok</status> <id>1325</id> </result> </del> </client> </packet>

If the operations failed, the response can look as follows:


<packet version=1.4.2.0> <client> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1325</id> </result> </del> </client> </packet>

100

Supported Operations

Setting Client Account Properties


The set operation is used to update Plesk client account settings.

In this section:
Request Packet Structure.................................................................................. 100 Request Samples .............................................................................................. 101 Response Packet Structure ............................................................................... 105 Response Samples ........................................................................................... 106

Request Packet Structure


A request XML packet setting various settings for the specified client account includes the set operation node:
<packet version=1.4.2.0> <client> <set> </set> </client> </packet>

The set node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). The set node has the following graphics representation:

The filter node is required. It specifies the filtering rule. Data type: clientSelectionFilterType (client_input.xsd). For more information on filters, refer to the Filtering Issues (on page 60) section. The values node is required. It is used to specify the categories of settings that will be set to Plesk database. Data type: none.

Supported Operations

101

The gen_info node is optional. It specifies a collection of general settings. Data type: clientSetGenInfo (plesk_client.xsd). See the structure of this node in topic General Client Account Settings (see page 64). The limits node is optional. It specifies a collection of limits set for the specified client account. Data type: clientLimits (plesk_client.xsd). For details, refer to the Limits and Permissions (on page 70) section. The permissions node is optional. It specifies a collection of Plesk client permissions. Data type: clientPerms (plesk_client.xsd). For details, refer to the Limits and Permissions (on page 70) section. The sbnet-user node is optional. It is used to enable/disable the creation of a SiteBuilder user account for this Plesk client. Data type: Boolean. The feature is supported by Plesk for Windows since API RPC protocol v.1.4.2.0 and by Plesk for Unix since API RPC protocol v.1.5.2.0.

Request Samples
In API RPC 1.5.2.0 and later versions, you can change a client GUID using the following packet:
<packet version=1.5.2.0> <client> <set> <filter> <login>MyClient</login> </filter> <values> <gen_info> <guid/> </gen_info> <values> </set> </client> </packet>

To change GUIDs of all clients, use the following packet:


<packet version=1.5.2.0> <client> <set> <filter/> <values> <gen_info> <guid/> </gen_info> <values> </set> </client> </packet>

102

Supported Operations

If you use API RPC 1.5.0.0 or later versions, a typical request packet changing client settings can look as follows:
<packet version=1.5.0.0> <client> <set> <filter> <login>technolux</login> <login>advent</login> </filter> <values> <limits> <limit> <name>disk_space</name> <value>209715200</value> </limit> <limit> <name>max_dom</name> <value>50</value> </limit> <limit> <name>max_subdom</name> <value>250</value> </limit> <limit> <name>max_webapps</name> <value>30</value> </limit> <limit> <name>max_traffic</name> <value>209715200</value> </limit> <limit> <name>max_db</name> <value>30</value> </limit> <limit> <name>expiration</name> <value>1134616208</value> </limit> </limits> </values> </set> </client> </packet>

Supported Operations

103

If you use API RPC 1.4.2.0 or earlier versions, the request packet looks as follows:
<packet version=1.4.2.0> <client> <set> <filter> <id>1324</id> <id>1325</id> </filter> <values> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> </values> </set> </client> </packet>

Or:
<packet version=1.4.2.0> <client> <set> <filter> <login>technolux</login> <login>advent</login> </filter> <values> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> </values> </set> </client> </packet>

104

Supported Operations

The following packet is invalid as it uses both filtering parameters within the same filter:
<packet version=1.4.2.0> <client> <set> <filter> <id>1324</id> <login>advent</login> </filter> <values> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> </values> </set> </client> </packet>

To fix this packet, use multiple set operations:


<packet version=1.4.2.0> <client> <set> <filter> <id>1324</id> </filter> <values> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> </values> </set> <set> <filter> <login>advent</login> </filter> <values> <limits> <disk_space>209715200</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>209715200</max_traffic> <max_db>30</max_db> <expiration>1134616208</expiration> </limits> </values> </set> </client></packet>

Supported Operations

105

Response Packet Structure


The set node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested set operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the set operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the set operation fails. Data type: string. The filter-id node is optional. Returns the name or ID of a client depending on a way of client specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. Data type: anySimple. The id node is optional. It is required if the set operation succeeds. Returns the unique identifier of the client account just updated. Data type: integer.

106

Supported Operations

Response Samples
Once the specified client accounts are updated, the response packet as follows is received from the server:
<packet version=1.4.2.0> <client> <set> <result> <status>ok</status> <id>1324</id> </result> <result> <status>ok</status> <id>1325</id> </result> </set> </client> </packet>

If the set operations fails, the response can look as follows:


<packet version=1.4.2.0> <client> <set> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1324</id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> </set> </client> </packet>

Supported Operations

107

Adding IP Addresses to Clients IP Pool


The ippool_add_ip operation is used to add IP addresses to the IP pool of the specified client account.

In this section:
Request Packet Structure.................................................................................. 107 Request Samples .............................................................................................. 108 Response Packet Structure ............................................................................... 108 Response Samples ........................................................................................... 109

Request Packet Structure


A request XML packet adding a new IP address to the IP pool of the specified Plesk client includes the ippool_add_ip node:
<packet version=1.4.2.0> <client> <ippool_add_ip> </ippool_add_ip> </client> </packet>

The ippool_add_ip node is specified by type ipPoolOperateType (plesk_client.xsd). The ippool_add_ip node has the following graphics representation:

The client_id node is required. It specifies the unique identifier of the client account whose IP pool is added with new IP addresses. Data type: integer. The ip_address node is required. It specifies the IP address to be added to the IP pool of the specified Plesk clients. Data type: ip_address (common.xsd).

108

Supported Operations

Request Samples
To add an IP address to the clients IP pool, specify the packet as follows:
<packet version=1.4.2.0> <client> <ippool_add_ip> <client_id>1234</client_id> <ip_address>192.0.2.122</ip_address> <ip_address>192.0.2.123</ip_address> </ippool_add_ip> </client> </packet>

Response Packet Structure


The ippool_add_ip node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested ippool_add_ip operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the ippool_add_ip operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the ippool_add_ip operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the ippool_add_ip operation fails. Data type: string. The ip_address node is optional. It is required if the ippool_add_ip operation succeeds. Returns the IP address added to the IP pool of the specified client account(s). Data type: ip_address (common.xsd). The client_id node is optional. It is required if the ippool_add_ip operation succeeds. Returns the unique identifier of the client account whose IP pool is enlarged with the specified IP address. Data type: integer.

Supported Operations

109

Response Samples
A positive response packet received from the server can look as follows:
<packet version=1.4.2.0> <client> <ippool_add_ip> <result> <status>ok</status> <client_id>1234</client_id> <ip_address>192.0.2.122</ip_address> <ip_address>192.0.2.123</ip_address> </result> </ippool_add_ip> </client> </packet>

If the ippool_add_ip operations fails, the negative response can look as follows:
<packet version=1.4.2.0> <client> <ippool_add_ip> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </ippool_add_ip> </client> </packet>

Removing IP Addresses from the Clients IP Pool


The ippool_del_ip operation is used to remove IP addresses from the IP pool of the specified client account. Note: You cannot remove an IP address from IP pool of a Plesk user who shares this IP with other Plesk users.

In this section:
Request Packet Structure.................................................................................. 110 Request Samples .............................................................................................. 110 Response Packet Structure ............................................................................... 111 Response Samples ........................................................................................... 112

110

Supported Operations

Request Packet Structure


A request XML packet removing IP addresses from the IP pool of the specified Plesk client includes the ippool_del_ip operation node:
<packet version=1.4.2.0> <client> <ippool_del_ip> </ippool_del_ip> </client> </packet>

The ippool_del_ip node is specified by type ipPoolOperateType (plesk_client.xsd). The ippool_add_ip node has the following graphics representation:

The client_id node is required. It specifies Plesk client from whose IP pool the specified IP addresses are taken away. Data type: integer. The ip_address node is required. It specifies the IP address that will be removed from the IP pool of the specified Plesk clients. Data type: string.

Request Samples
To remove the specified IP addresses from the clients IP pool, specify the packet as follows:
<packet version=1.4.2.0> <client> <ippool_del_ip> <client_id>1234</client_id> <ip_address>192.0.2.122</ip_address> <ip_address>192.0.2.123</ip_address> </ippool_del_ip> </client> </packet>

Supported Operations

111

Response Packet Structure


The ippool_del_ip node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested ippool_del_ip operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the ippool_del_ip operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the ippool_del_ip operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the ippool_del_ip operation fails. Data type: string. The ip_address node is optional. It is required if the ippool_del_ip operation succeeds. Returns the IP address removed from the IP pool of the specified client accounts. Data type: string. The client_id node is optional. It is required if the ippool_del_ip operation succeeds. Returns the unique identifier of the client account from whose IP pool the specified IP address (or several) is removed. Data type: integer. (integer).

112

Supported Operations

Response Samples
A positive response packet received from the server can look as follows:
<packet version=1.4.2.0> <client> <ippool_del_ip> <result> <status>ok</status> <client_id>1234</client_id> <ip_address>192.0.2.122</ip_address> <ip_address>192.0.2.123</ip_address> </result> </ippool_del_ip> </client> </packet>

If the ippool_del_ip operations failed, the response can look as follows:


<packet version=1.4.2.0> <client> <ippool_del_ip> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </ippool_del_ip> </client> </packet>

Listing Buttons Displayed on the Clients Page in Control Panel


The cform_buttons_list operation is used to retrieve the list of buttons displayed on a client's home page.

In this section:
Request Packet Structure.................................................................................. 113 Request Samples .............................................................................................. 113 Response Packet Structure ............................................................................... 115 Response Samples ........................................................................................... 118

Supported Operations

113

Request Packet Structure


A request XML packet getting the list of buttons of the specified client account from Plesk database includes the cform_buttons_list operation node:
<packet version=1.4.2.0> <client> <cform_buttons_list> </cform_buttons_list> </client> </packet>

The cform_buttons_list operation node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). The cform_buttons_list node has the following graphics representation:

The filter node is required. It specifies the filtering rule. Data type: clientSelectionFilterType (client_input.xsd). For more information on filters, refer to the Filtering Issues (on page 60) section.

Request Samples
A single request packet can retrieve the list the buttons for a single Plesk client or multiple Plesk clients. If multiple Plesk clients are requested, they can be filtered either by id or by login:
<packet version=1.4.2.0> <client> <cform_buttons_list> <filter> <id>1324</id> <id>1325</id> </filter> </cform_buttons_list> </client> </packet>

114

Supported Operations

Or:
<packet version=1.4.2.0> <client> <cform_buttons_list> <filter> <login>technolux</login> <login>advent</login> </filter> </cform_buttons_list> </client> </packet>

The following packet is invalid as it uses both id and login in the same filter:
<packet version=1.4.2.0> <client> <cform_buttons_list> <filter> <id>1324</id> <login>advent</login> </filter> </cform_buttons_list> </client> </packet>

To fix this packet, use multiple cform_buttons_list sections:


<packet version=1.4.2.0> <client> <cform_buttons_list> <filter> <id>1324</id> </filter> </cform_buttons_list> <cform_buttons_list> <filter> <login>advent</login> </filter> </cform_buttons_list> </client> </packet>

Supported Operations

115

Response Packet Structure


A response cform_buttons_list packet structure is specified in the client_output.xsd schema as follows:

The result node is required. It wraps the result of the requested cform_buttons_list operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the cform_buttons_list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the cform_buttons_list operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the cform_buttons_list operation fails. Data type: string. The filter-id node is optional. Returns the name or ID of a client depending on a way of client specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. Data type: anySimple. The id node is optional. It is required if the cform_buttons_list operation succeeds. Returns the unique identifier of the client account whose list of buttons is returned. Data type: integer. The button node is optional. It is present if the cform_buttons_list operation succeeds. Returns a single button displayed on the client's home page. Data type: buttonDataType (plesk_common.xsd). See the structure of this node below.

116

Supported Operations

The button node is structured as follows:

The code node is required. It specifies the button's identifier. Data type: string.

Supported Operations

117

The type node is required. It specifies the button's type (a link or a standard button). Data type: string. Allowed values: link_button | comm_button. The name node is required. It specifies the localized caption displayed on the button in Plesk GUI. Data type: string. The name_id node is required. It specifies the localization key of the button's name. Data type: string. The group_name node is required. It specifies the localized name of the section in which the button is located in Plesk GUI. Data type: string. The group_name_id node is required. It specifies the localization key of the section name. Data type: string. The href node is required. It specifies the URL referenced by the button. Data type: string. The js_onclick node is optional. It specifies a piece of the JavaScript code executed at the button click. Data type: text. The enabled node is required. It specifies whether the button is enabled/disabled. Data type: Boolean. The new_window node is optional. It indicates whether a new window will be opened at a button click. Data type: Boolean. The tabindex node is optional. It specifies the tabulation index of the button. Data type: integer. Default value: 0. The conhelp_id node is optional. It specifies the localization key of the context help message associated with the button. Data type: string. The conhelp node is optional. It specifies a context help message displayed for the button. Data type: text. The icon_url node is optional. It specifies the URL of the buttons icon. Data type: string.

118

Supported Operations

Response Samples
A positive response received from the server returns the clients identifier and one to many button elements, each describing a single button:
<packet version=1.5.0.0> <client> <cform_buttons_list> <result> <status>ok</status> <filter-id>1324</filter-id> <id>1324</id> <button> <code>EDIT_BUTTON</code> <type>link_button</type> <name>Edit</name> <name_id>edit</name_id> <group_name>Tools</group_name> <group_name_id>__tools</group_name_id> <href>/clients/cl_ed.php3</href> <enabled>true</enabled> <new_window>false</new_window> </button> </result> </cform_buttons_list> </client> </packet>

If the operation fails, the negative response packet can look as follows:
<packet version=1.5.0.0> <client> <cform_buttons_list> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <filter-id>1324</filter-id> </result> </cform_buttons_list> </client> </packet>

Supported Operations

119

Retrieving Descriptor of Limits


Use the get-limit-descriptor operation to retrieve descriptor of client's limits. For details on descriptors, refer to the Representation of Object Descriptor (on page 47) section. For details on client's limits, refer to the Limits (on page 77) section.

In this section:
Request Packet Structure.................................................................................. 119 Request Samples .............................................................................................. 120 Response Packet Structure ............................................................................... 121 Response Samples ........................................................................................... 121

Request Packet Structure


A request XML packet retrieving client limits descriptors includes the get-limit-descriptor operation node:
<packet version=1.5.0.0> <client> <get-limit-descriptor> </get-limit-descriptor> </client> </packet>

You can retrieve descriptor for the specified client, or the server-level client limits descriptor. The get-limit-descriptor node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: clientSelectionFilterType (client_input.xsd). For information on filters, refer to the Filtering Issues (on page 60) section.

120

Supported Operations

Request Samples
The request packet retrieving limits descriptor for the client with ID 5 looks as follows:
<packet version ="1.5.0.0"> <client> <get-limit-descriptor> <filter> <id>5</id> </filter> </get-limit-descriptor> </client> </packet>

The request packet retrieving limits descriptor for the clients with ID 5 and ID 7 looks as follows:
<packet version ="1.5.0.0"> <client> <get-limit-descriptor> <filter> <id>5</id> <id>7</id> </filter> </get-limit-descriptor> </client> </packet>

The request packet retrieving the server-level descriptor of client limits looks as follows:
<packet version ="1.5.0.0"> <client> <get-limit-descriptor> <filter/> </get-limit-descriptor> </client> </packet>

Supported Operations

121

Response Packet Structure


The get-limit-descriptor node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (plesk_common.xsd). The status node is required. It specifies the execution status of the get-limit-descriptor operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get-limitdescriptor operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the get-limitdescriptor operation fails. Data type: string. The filter-id node is optional. It is required if the get-limit-descriptor operation succeeds. Returns the name or ID of a client depending on a way of client specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. For info on filters, refer to the Filters of Descriptors (on page 48) section. Data type: anySimple. The id node is optional. It is required if the get-limit-descriptor operation succeeds. Returns the unique identifier of the client account. Data type: integer. The descriptor node is optional. It specifies the object descriptor. For details, refer to Representation of Object Descriptor (on page 47). Data type: string.

Note: This descriptor contains limits extensions. For details, refer to the Extension of Limits Descriptor (see page 53) section.

122

Supported Operations

Response Samples
If a limit name was not found on the server, the response can look as follows:
<packet version ="1.5.0.0"> <client> <set> <result> <status>error</status> <errcode>1002</errcode> <errtext>Unknown limit name: my_limit</errtext> </result> </set> </client> </packet>

A possible response from the server can look as follows:


<packet version ="1.5.0.0"> <client> <get-limit-descriptor> <result> <status>ok</status> <filter-id>5</filter-id> <id>5</id> <descriptor> <property> <name>max_dom</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_dom</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_subdom</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_subdom</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_dom_aliases</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_dom_aliases</label> <extension> <shared>false</shared> </extension> </property> <property> <name>disk_space</name> <type>bytes</type> <writable-by>admin</writable-by> <label>limit__disk_space</label> <extension> <shared>false</shared>

Supported Operations </extension> </property> <property> <name>max_traffic</name> <type>bytes</type> <writable-by>admin</writable-by> <label>limit__max_traffic</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_wu</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_wu</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_db</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_db</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_box</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_box</label> <extension> <shared>false</shared> </extension> </property> <property> <name>mbox_quota</name> <type>bytes</type> <writable-by>admin</writable-by> <label>limit__mbox_quota</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_redir</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_redir</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_mg</name> <type>int</type> <writable-by>admin</writable-by>

123

124

Supported Operations <label>limit__max_mg</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_resp</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_resp</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_maillists</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_maillists</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_webapps</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_webapps</label> <extension> <shared>false</shared> </extension> </property> <property> <name>expiration</name> <type>date</type> <writable-by>admin</writable-by> <label>limit__expiration</label> <extension> <shared>true</shared> </extension> </property> </descriptor> </result> </get-limit-descriptor> </client> </packet>

Supported Operations

125

Retrieving Descriptor of Permissions


Use the get-permission-descriptor operation to retrieve descriptor of client's permissions. For details on descriptors, refer to the Representation of Object Descriptor (on page 47) section. For details on client's permissions, refer to the Permissions (on page 79) section.

In this section:
Request Packet Structure.................................................................................. 125 Request Samples .............................................................................................. 126 Response Packet Structure ............................................................................... 127 Response Samples ........................................................................................... 127

Request Packet Structure


A request XML packet retrieving client permissions preferences includes the getpermission-descriptor operation node:
<packet version=1.5.0.0> <client> <get-permission-descriptor> </get-permission-descriptor> </client> </packet>

You can retrieve permissions descriptor for the specified client, or the server-level client permissions descriptor. The get-permission-descriptor node has the following graphical representation:

The filter node is required. It specifies a filtering rule. Data type: clientSelectionFilterType (client_input.xsd). For information on filters, refer to the Filtering Issues (on page 60) section.

126

Supported Operations

Request Samples
The request packet retrieving permissions descriptor for the client with ID 5 looks as follows:
<packet version ="1.5.0.0"> <client> <get-permission-descriptor> <filter> <id>5</id> </filter> </get-permission-descriptor> </client> </packet>

The request packet retrieving permissions descriptor for MyClient and MyClient2 clients looks as follows:
<packet version ="1.5.0.0"> <client> <get-permission-descriptor> <filter> <login>MyClient</login> <login>MyClient2</login> </filter> </get-permission-descriptor> </client> </packet>

The request packet retrieving the server-level descriptor of client permissions looks as follows:
<packet version ="1.5.0.0"> <client> <get-permission-descriptor> <filter/> </get-permission-descriptor> </client> </packet>

Supported Operations

127

Response Packet Structure


The get-permission-descriptor node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (plesk_common.xsd). The status node is required. It specifies the execution status of the get-permissiondescriptor operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the getpermission-descriptor operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the getpermission-descriptor operation fails. Data type: string. The filter-id node is optional. It is required if the get-permission-descriptor operation succeeds. Returns the name or ID of a client depending on a way of client specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. For info on filters, refer to the Filters of Descriptors (on page 48) section. Data type: anySimple. The id node is optional. It is required if the get-permission-descriptor operation succeeds. Returns the unique identifier of the client account. Data type: integer. The descriptor node is optional. It specifies the object descriptor. For details, refer to Representation of Object Descriptor (on page 47). Data type: string.

Note: This descriptor contains permissions extensions. For details, refer to the Extension of Permissions Descriptor (on page 51) section.

128

Supported Operations

Response Samples
A positive response from the server can look as follows:
<packet version="1.5.0.0"> <client> <get-permission-descriptor> <result> <status>ok</status> <descriptor> <property> <name>cp_access</name> <type>boolean</type> <default-value>true</default-value> <writable-by>admin</writable-by> <label>cl_perm__cp_access</label> <extension> <level>client</level> <level>mail</level> </extension> </property> <property> <name>create_domains</name> <type>boolean</type> <default-value>false</default-value> <writable-by>admin</writable-by> <label>cl_perm__create_domains</label> <extension> <level>client</level> </extension> </property> ... </descriptor> </result> </get-permission-descriptor> </client> </packet>

Supported Operations

129

Upgrading Client Account to Reseller Account


The convert-to-reseller operation is used to upgrade client accounts to reseller accounts. Note: The operation is supported since protocol version 1.6.0.0.

In this section:
Request Packet Structure.................................................................................. 129 Request Samples .............................................................................................. 130 Response Packet Structure ............................................................................... 130 Response Samples ........................................................................................... 131

Request Packet Structure


A request XML packet upgrading client accounts to reseller accounts includes the convert-to-reseller node:
<packet version=1.6.0.0> <client> <convert-to-reseller> </convert-to-reseller> </client> </packet>

The convert-to-reseller node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: clientSelectionFilterType. For more information on filters, refer to the Filtering Issues section (on page 60).

130

Supported Operations

Request Samples
The request packet updating a client account to a reseller account looks as follows:
<packet version ="1.6.0.0"> <client> <convert-to-reseller> <filter> <owner-login>JDoe</owner-login> </filter> </convert-to-reseller> </client> </packet>

Response Packet Structure


The convert-to-reseller node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (plesk_common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the operation fails. Data type: unsignedInt.

Supported Operations

131

The errtext node is optional. Can be used to return the error message if the operation fails. Data type: string. The filter-id node is optional. Returns the filtering parameter. Data type: anySimple. The id node is optional. It is required if the operation succeeds. Returns the unique identifier of the reseller account. Data type: integer.

Response Samples
A positive response packet received from the server can look as follows:
<packet version=1.6.0.0> <client> <convert-to-reseller> <result> <status>ok</status> <filter-id>JDoe</filter-id> <id>192</id> </result> </convert-to-reseller> </client> </packet>

If the operations failed, the response can look as follows:


<packet version=1.6.0.0> <client> <convert-to-reseller> <result> <status>error</status> <errcode>1013</errcode> <errtext>Client does not exist</errtext> <filter-id>JDoe</filter-id> </result> </convert-to-reseller> </client> </packet>

132

Supported Operations

Changing Client Account Owner


The change-owner operation is used to change the owner of a client account. Note: The operation is supported for protocol version 1.6.0.0 and later.

In this section:
Request Packet Structure.................................................................................. 132 Request Samples .............................................................................................. 133 Response Packet Structure ............................................................................... 133 Response Samples ........................................................................................... 134

Request Packet Structure


A request XML packet assigning a new owner to a client account includes the changeowner node:
<packet version=1.6.0.0> <client> <change-owner> </change-owner> </client> </packet>

The change-owner node does not have a separate type, it is nested within the ClientTypeRequest complex type (client_input.xsd). The change-owner node graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: clientSelectionFilterType. For more information on filters, refer to the Filtering Issues (on page 60) section. The new-owner-id node is required. It specifies the ID of a new client account owner. Data type: integer. The new-owner-login node is required. It specifies the login name of a new client account owner. Data type: string.

Supported Operations

133

Request Samples
The request packet assigning a new owner to a client account looks as follows:
<packet version ="1.6.0.0"> <client> <change-owner> <filter> <owner-login>JDoe</owner-login> </filter> <new-owner-login>RRoe</new-owner-login> </change-owner> </client> </packet>

Response Packet Structure


The change-owner node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the change-owner operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the change-owner operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the change-owner operation fails. It returns the error message. Data type: string. The filter-id node is required if the change-owner operation succeeds. It returns the filtering parameter. Data type: anySimple.

134

Supported Operations

The id node is required if the change-owner operation succeeds. It returns ID of the client account which owner was changed. Data type: id_type (common.xsd).

Response Samples
A positive response packet received from the server can look as follows:
<packet version=1.6.0.0> <client> <change-owner> <result> <status>ok</status> <filter-id>JDoe</filter-id> <id>2</id> </result> </change-owner> </client> </packet>

If the operations failed, the response can look as follows:


<packet version=1.6.0.0> <client> <change-owner> <result> <status>error</status> <errcode>1013</errcode> <errtext>Owner does not exist</errtext> <filter-id>JDoe</filter-id> </result> </change-owner> </client> </packet>

Supported Operations

135

Managing Client Templates


Operator: <client-template> XML Schema: client_template.xsd Plesk version: Plesk 8.0 for UNIX | Plesk 7.6 for Windows and higher API RPC version: 1.4.1.0 and higher Plesk user: Plesk Administrator Description Client templates are a kind of presets which are used for creating multiple client accounts with identical permissions, limits, IP pool settings, and preferences. Supported operations

ADD (see page 143) creates a client template GET (see page 148) retrieves information on a particular client template DEL (see page 153) removes a client template SET (see page 156) updates preferences, limits, and IP pool configuration set for a client template

In this section:
Client Template Settings ................................................................................... 136 Filtering Issues .................................................................................................. 142 Creating Client Template ................................................................................... 143 Retrieving Information on Client Templates ....................................................... 148 Removing Client Templates .............................................................................. 153 Updating Client Template Settings .................................................................... 156

136

Supported Operations

Client Template Settings


This section describes a collection of Plesk client settings that can be defined in a client template. These settings can be specified when creating a client template or later.

In this section:
Permissions....................................................................................................... 136 Limits................................................................................................................. 138 IP Pool Settings................................................................................................. 140 Preferences ....................................................................................................... 141

Permissions
For details on client permissions, refer to the Limits and Permissions (on page 70) section. Samples The "Limits" XML schema is the same for client and client template. In API RPC 1.5.0.0 and later versions, a packet that requests for creating a new client template and with a collection of permissions can look as follows:
<packet version=1.5.0.0> <client-template> <add> <name>base_template</name> <permissions> <permission> <name>create_domains</name> <value>true</value> </permission> <permission> <name>manage_phosting</name> <value>true</value> </permission> <permission> <name>manage_quota</name> <value>true</value> </permission> <permission> <name>manage_domain_aliases</name> <value>true</value> </permission> <permission> <name>manage_subdomains</name> <value>true</value> </permission>

Supported Operations <permission> <name>manage_dns</name> <value>true</value> </permission> <permission> <name>manage_log</name> <value>true</value> </permission> <permission> <name>manage_anonftp</name> <value>true</value> </permission> <permission> <name>manage_subftp</name> <value>true</value> </permission> <permission> <name>manage_webapps</name> <value>true</value> </permission> <permission> <name>remote_access_interface</name> <value>true</value> </permission> <permission> <name>cp_access</name> <value>true</value> </permission> <permission> <name>stdgui</name> <value>true</value> </permission> <permission> <name>dashboard</name> <value>true</value> </permission> <permission> <name>manage_dashboard</name> <value>true</value> </permission> <permission> <name>allow_local_backups</name> <value>true</value> </permission> </permissions> </add> </client-template> </packet>

137

138

Supported Operations

In API RPC 1.4.2.0 and earlier versions, a packet that requests for creating a new client template and with a collection of permissions can look as follows:
<packet version=1.4.2.0> <client-template> <add> <name>base_template</name> <permissions> <create_domains>true</create_domains> <manage_phosting>true/manage_phosting> <manage_quota>true</manage_quota> <manage_domain_aliases>true</manage_domain_aliases> <manage_subdomains>true</manage_subdomains> <manage_dns>true</manage_dns> <manage_log>true</manage_log> <manage_anonftp>true</manage_anonftp> <manage_subftp>true</manage_subftp> <manage_webapps>true</manage_webapps> <remote_access_interface>true</remote_access_interface> <cp_access>true</cp_access> <stdgui>true</stdgui> <dashboard>true</dashboard> <manage_dashboard>true</manage_dashboard> <allow_local_backups>true</allow_local_backups> </permissions> </add> </client-template> </packet>

Limits
Client template limits and client limits are described by the same XML structures. The only difference between descriptions of these two objects is in names of types that define XML structures: The former is of clientLimits type, while the latter is of clientTemplateLimits type. For details on client limits description, refer to the Limits and Permissions (on page 70) section. Samples In API RPC 1.5.0.0 and later versions, a packet that requests for creating a new client template and with a collection of limits can look as follows:
<packet version=1.5.0.0> <client-template> <add> <name>base_template</name> <limits> <limit> <name>disk_space</name> <value>209715200</value> </limit> <limit> <name>mysql_dbase_space</name> <value>52428800</value>

Supported Operations </limit> <limit> <name>max_db</name> <value>50</value> </limit> <limit> <name>max_traffic</name> <value>52428800</value> </limit> <limit> <name>max_dom</name> <value>100</value> </limit> <limit> <name>max_dom_aliases</name> <value>5</value> </limit> <limit> <name>max_subdom</name> <value>400</value> </limit> <limit> <name>total_mboxes_ quota</name> <value>1000</value> </limit> <limit> <name>expiration</name> <value>63072000</value> </limit> </limits> </add> </client-template> </packet>

139

In API RPC 1.4.2.0 and earlier versions, a packet that requests for creating a new client template and with a collection of limits can look as follows:
<packet version=1.4.2.0> <client-template> <add> <name>base_template</name> <limits> <disk_space>209715200</disk_space> <mysql_dbase_space>52428800</mysql_dbase_space> <max_db>50</max_db> <max_traffic>52428800</max_traffic> <max_dom>100</max_dom> <max_dom_aliases>5</max_dom_aliases> <max_subdom>400</max_subdom> <total_mboxes_ quota>1000</total_mboxes_quota> <expiration>63072000</expiration> </limits> </add> </client-template> </packet>

140

Supported Operations

IP Pool Settings
A client template holds IP pool settings for clients that will be created using this template. The client IP pool can contain a set of shared and exclusive IP addresses. Shared IP addresses are selected from Plesk server IP pool. Exclusive IP addresses are created for the client. IP pool settings are specified by the ip-pool node which is presented by the ClienttemplatePoolType complex type (client_template.xsd). It is structured as follows:

The ip-address node is optional. It specifies the IP address available in Plesk IP pool. Data type: ip_address (common.xsd). The allocate-ip node is optional. It specifies the number of exclusive IP addresses. Data type: integer.

The following request packet creates a client template for Plesk Administrator and specifies IP pool settings for the template:
<packet version=1.6.0.0> <client-template> <add> <name>base_template</name> <ip-pool> <ip-address>196.0.2.121</ip-address> <ip-address>196.0.2.122</ip-address> <allocate-ip>2</allocate-ip> </ip-pool> <owner-login>admin</owner-login> </add> </client-template> </packet>

Supported Operations

141

Preferences
Preferences for clients created with a client template are specified by the preferences node. This node is presented by the ClientTemplatePreferencesType complex type (plesk_client.xsd). It is structured as follows:

The sbnet-user node is optional. It indicates whether a Plesk client created using this client template can have a Sitebuilder user account. The feature is supported by Plesk for Windows since API RPC protocol v.1.4.2.0 and by Plesk for Unix since API RPC protocol v.1.5.2.0. The shared node is optional. It indicates whether other Plesk users have access to this template. Specify this option only for client templates created by Plesk Administrator. Data type: boolean. Supported since protocol version 1.6.0.0.

Note: The preferences node is supported by API RPC 1.4.2.0 and later. The following request packet creates a client template and sets preferences for it:
<packet version=1.6.0.0> <client-template> <add> <name>base_template</name> <preferences> <sbnet-user>true</sbnet_user> <shared>false</shared> </preferences> <owner-id>3</owner-id> </add> </client-template> </packet>

142

Supported Operations

Filtering Issues
Filtering is the way a request XML packet indicates the object (one or several client templates) to which an operation is to be applied. Parameters nested within the filter node are called filtering rule. The filter node is presented by the ClientTemplateFilterType complex type (client_template.xsd). This data type is structured as follows:

The id node is required. It specifies the client template ID which is unique for a template owner. Data type: integer. The name node is required. It specifies the client template name which is unique for a template owner. Data type: string.

Note: Different client templates which belong to different Plesk users can have the same ID or name. A client template can be filtered either by id, or by name. The same is true if several client templates are filtered by the same filter node. The following sample packet is invalid as it uses both id and name within the same filter:
<packet version=1.6.0.0> <client-template> <get> <filter> <name>base_template</name> <name>quick_template</name> <id>11</id> <id>12</id> </filter> <limits/> <owner-login>JDoe</owner-login> </get> </client-template> </packet>

Supported Operations

143

To fix this packet, use two different <get> sections instead:


<packet version=1.6.0.0> <client-template> <get> <filter> <name>base_template</name> <name>quick_template</name> </filter> <limits/> <owner-login>JDoe</owner-login> </get> <get> <filter> <id>11</id> <id>12</id> </filter> <limits/> <owner-login>JDoe</owner-login> </get> </client-template> </packet>

The filter node can be left empty. In this case all client templates belong to one Plesk user will be filtered:
<packet version=1.6.0.0> <client-template> <get> <filter/> <owner-id>4</owner-id> </get> </client-template> </packet>

144

Supported Operations

Creating Client Template


The add operation is used to create client templates.

In this section:
Request Packet Structure.................................................................................. 144 Request Samples .............................................................................................. 145 Response Packet Structure ............................................................................... 146 Response Samples ........................................................................................... 147

Request Packet Structure


A request XML packet adding a new client template to Plesk database includes the add operation node:
<packet version=1.6.0.0> <client-template> <add> </add> </client-template> </packet>

The add node is presented by type ClienttemplateAddInputType (client_template.xsd). Its graphical representation is as follows:

The name node is required. It specifies client template name unique for the template owner. Data type: string. The limits node is optional. It specifies a collection of limits that will be set for clients created using this template. Data type: clientLimits (plesk_client.xsd). To view the structure of this node, refer to the Limits (see page 138) section.

Supported Operations

145

The permissions node is optional. It specifies a collection of permissions for clients created using this template. Data type: clientPerms (plesk_client.xsd). To view the structure of this node, refer to the Permissions (on page 136) section. The ip-pool node is optional. It specifies IP pool settings for clients created using this template. Data type: clienttemplateIpPoolType (client_template.xsd). To view the structure of this node, refer to the IP Pool Settings (see page 140) section. The preferences node is optional. It specifies a collection of preferences for clients created using this template. Data type: ClientTemplatePreferencesType (client_template.xsd). To view the structure of this node, refer to the Preferences (see page 141) section. The owner-id node is required. It specifies the ID of the client template owner. Data type: integer. The node is supported since protocol version 1.6.0.0. The owner-login node is required. It specifies the login name of the client template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

Request Samples
The following packet creates a client template with a minimal collection of settings.
<packet version=1.6.0.0> <client-template> <add> <name>base_template</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> <owner-id>2</owner-id> </add> </client-template> </packet>

To create two client templates with a single packet, include two different add operations:
<packet version=1.6.0.0> <client-template> <add> <name>base_template</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> <owner-login>JDoe</owner-login> </add> <add> <name>quick_template</name> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> </ip-pool> <owner-id>4</owner-id> </add> </client-template> </packet>

146

Supported Operations

Response Packet Structure


The add node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ClientTemplateOutputResulttype (client_template.xsd). The status node is required. It specifies the execution status of the add operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the add operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the add operation fails. It returns the error message. Data type: string. The id node is required if the add operation succeeds. It returns the ID of the created client account. Data type: integer. The name node is required if the add operation succeeds. It returns the name of the created client template. Data type: string.

Supported Operations

147

Response Samples

A positive response received from the server after adding a new client template can look as follows:
<packet version=1.4.2.0> <client-template> <add> <result> <status>ok</status> <id>24</id> <name>base_template</name> </result> </add> </client-template> </packet>

A negative response can look as follows:


<packet version=1.4.2.0> <client-template> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </add> </client-template> </packet>

148

Supported Operations

Retrieving Information on Client Templates


The get operation is used to retrieve information about client templates from Plesk database. This information is as follows: client template name and ID which are unique for the template owner permissions and limits on use Plesk resources IP pool settings preferences

The get operation can return all or particular settings currently present in Plesk database. All settings are optional and can be missing in the client template. A client template can even be empty (specified by its id and name and not containing any other information). The get operation will return only the settings currently stored in the database.

In this section:
Request Packet Structure.................................................................................. 148 Request Samples .............................................................................................. 150 Response Packet Structure ............................................................................... 151 Response Samples ........................................................................................... 152

Request Packet Structure


A request XML packet retrieving information on specified client templates from Plesk database includes the get operation node:
<packet version=1.6.0.0> <client-template> <get> </get> </client-template> </packet>

Supported Operations

149

The get node is presented by the ClientTemplateGetInputType complex type (client_template.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: ClientTemplateFilterType (client_template.xsd). To view the structure of this node, refer to the Filtering Issues (on page 142) section. The limits node is optional. It is used to request limits on Plesk resources set for a client template. Data type: none. The permissions node is optional. It is used to request permissions on Plesk resources set for a client template. Data type: none. The ip-pool node is optional. It is used to request IP pool settings defined for a client template. Data type: none. The preferences node is optional. It is used to request preferences set for a client template. Data type: none. The owner-id node is required. It specifies the ID of a client template owner . Data type: integer. The node is supported since protocol version 1.6.0.0. The owner-login node is required. It specifies the login name of a client template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

150

Supported Operations

Request Samples
The following packet requests all available information about two client templates:
<packet version=1.6.0.0> <client-template> <get> <filter> <name>base_template</name> <name>quick_template</name> </filter> <limits/> <permissions/> <ip-pool/> <preferences/> <owner-login>JDoe</owner-login> </get> </client-template> </packet>

To filter some client templates by id and others by name within the same packet, use two get operations:
<packet version=1.6.0.0> <client-template> <get> <filter> <name>base_template</name> <name>quick_template</name> </filter> <limits/> <owner-login>admin</owner-login> </get> <get> <filter> <id>12</id> </filter> <limits/> <owner-login>admin</owner-login> </get> </client-template> </packet>

To filter all client templates belong to one Plesk user, specify the packet as follows:
<packet version=1.6.0.0> <client-template> <get> <filter/> <owner-id>4</owner-id> </get> </client-template> </packet>

Supported Operations

151

This packet does not specify any particular settings, so the response packet will only return the list of identifiers and template names.

Response Packet Structure


The get node of the output XML packet is presented by the ClientTemplateOutputGetType (client_template.xsd). Its graphical representation is as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ClientTemplateOutputResulttype (client_template.xsd). The status node is required. It specifies the execution status of the get operation. Data type: result_status (common.xsd). Allowed values: ok | error. The errcode node is required if the get operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the get operation fails. It returns the error message. Data type: string. The id node is required if the get operation succeeds. It returns the ID of the client template which settings are retrieved in the response packet. Data type: integer. The name node is required if the get operation succeeds.It returns the name of the client template which settings are retrieved in the response packet. Data type: string. The limits node is required if the request get packet has the limits node and the operation succeeds. It returns limits on Plesk resources set for a client template. Data type: clientLimits (plesk_client.xsd). For more information on this node, refer to the Limits (see page 138) section.

152

Supported Operations

The permissions node is required if the request get packet has the permissions node, and the operation succeeds. It returns permissions set for a client template. Data type: clientPerms (plesk_client.xsd). For more information on this node, refer to the Permissions (on page 70) section. The ip-pool node is required if the request get packet specifies the ip-pool node, and the operation succeeds. It returns IP pool settings set for a client template. Data type: ClienttemplateIpPoolType (client_template.xsd). To view the structure of this node, refer to the IP Pool Settings (see page 140) section. The preferences node is required if the request get packet has the preferences node, and the operation succeeds. It returns preferences set for a client template. Data type: ClientTemplatePreferencesType (client_template.xsd). To view the structure of this node, refer to the Preferences (see page 141) section.

Response Samples
The following packet demonstrates a positive response received from Plesk server.
<packet version=1.4.2.0> <client-template> <get> <result> <status>ok</status> <id>24</id> <name>base_template</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> </result> <result> <status>ok</status> <id>12</id> <name>quick_template</name> <ip-pool> <ip-address>192.0.2.122</ip-address> <ip-address>192.0.2.123</ip-address> </ip-pool> </result> </get> </client-template> </packet>

Supported Operations

153

A negative response received from Plesk server can look as follows:


<packet version=1.4.2.0> <client-template> <get> <result> <status>error</status> <errcode>1027</errcode> <errtext>IP operation failed.</errtext> <id>24</id> <name>base_template</name> </result> <result> <status>error</status> <errcode>1027</errcode> <errtext>IP operation failed.</errtext> <id>12</id> <name>quick_template</name> </result> </get> </client-template> </packet>

Removing Client Templates


The del operation is used to remove client templates from Plesk database.

In this section:
Request Packet Structure.................................................................................. 153 Request Samples .............................................................................................. 154 Response Packet Structure ............................................................................... 155 Response Samples ........................................................................................... 156

Request Packet Structure


A request XML packet that removes client templates from Plesk database includes the del operation node:
<packet version=1.6.0.0> <client-template> <del> </del> </client-template> </packet>

154

Supported Operations

The del node is presented by type ClientTemplateDelInputType (client_template.xsd):

The filter node is required. It specifies the filtering rule. Data type: ClientTemplateFilterType (client_template.xsd). To view the structure of this node, refer to the Filtering Issues (on page 142) section. The owner-id node is required. It specifies the ID of a client template owner. Data type: id_type (common.xsd). The node is supported since protocol version 1.6.0.0. The owner-login node is required. It specifies the login name of a client template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

Request Samples
To select client templates for deletion, filter them either by id, or by name. The following packet is invalid as it uses both these nodes within one filter node:
<packet version=1.6.0.0> <client-template> <del> <filter> <name>base_template</name> <id>12</id> </filter> <owner-login>JDoe</owner-login> </del> </client-template> </packet>

To fix this issue, use different filter nodes (and different del operations):
<packet version=1.6.0.0> <client-template> <del> <filter> <name>base_template</name> </filter> <owner-login>JDoe</owner-login> </del> <del> <filter> <id>12</id> </filter> <owner-login>JDoe</owner-login> </del></client-template></packet>

Supported Operations

155

The following packet deletes all client templates belong to Plesk user:
<packet version=1.6.0.0> <client-template> <del> <filter/> <owner-id>3</owner-id> </del> </client-template> </packet>

Response Packet Structure


The del node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ClientTemplateOutputResulttype (client_template.xsd). The status node is required. It specifies the execution status of the del operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the del operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the del operation fails. It returns the error message. Data type: string. The id node is required if the del operation succeeds. It returns the ID of the removed client template. Data type: integer. The name node is required if the del operation succeeds. It returns the name of the removed client template. Data type: string.

156

Supported Operations

Response Samples
The following packet returns a positive response after the del operation is performed:
<packet version=1.4.2.0> <client-template> <del> <result> <status>ok</status> <name>base_template</name> </result> <result> <status>ok</status> <id>12</id> </result> </del> </client-template> </packet>

The first template was filtered by name (name = base_template), the second one was filtered by id (id = 12). A negative response received from Plesk server can look as follows:
<packet version=1.4.2.0> <client-template> <del> <result> <status>ok</status> <name>base_template</name> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>12</id> </result> </del> </client-template> </packet>

The deletion of the first client template (filtered by name = base_template) was successful, while the deletion of the second template (filtered by id = 12) failed.

Supported Operations

157

Updating Client Template Settings


The set operation is used to update client template settings. These settings are as follows: Permissions and limits on Plesk resources IP pool settings Preferences

You can update all settings of a domain template at once, or specify particular settings.

In this section:
Request Packet Structure.................................................................................. 157 Request Samples .............................................................................................. 158 Response Packet Structure ............................................................................... 159 Response Samples ........................................................................................... 161

Request Packet Structure


A request XML packet updating client template settings includes the set operation node:
<packet version=1.6.0.0> <client-template> <set> </set> </client-template> </packet>

The set node is presented by the ClientTemplateSetInputType complex type (client_template.xsd). Its graphical representation is as follows:

158

Supported Operations

The filter node is required. It specifies the filtering rule. Data type: ClientTemplateFilterType (client_template.xsd). For information on filters, refer to the Filtering Issues (on page 142) section. The limits node is optional. It specifies limits on Plesk resources for clients created with a client template. Data type: clientLimits (plesk_client.xsd). To view structure of this node, refer to the Limits (see page 138) section. The permissions node is optional. It specifies permissions for clients created with a client template. Data type: clientPerms (plesk_client.xsd). To view the structure of this node, refer to the Permissions (on page 136) section. The ip-pool node is optional. It specifies IP pool settings for clients created with a client template. Data type: ClienttemplateIpPoolType (client_template.xsd). To view the structure of this node, refer to the IP Pool Settings (see page 140) section. The preferences node is optional. It specifies preferences for clients created with a client template. Data type: ClientTemplatePreferencesType (client_template.xsd). To view the structure of this node, refer to the Preferences (see page 141) section. The owner-id node is required. It specifies the ID of a client template owner. Data type: id_type (common.xsd). The node is supported since protocol version 1.6.0.0. The owner-login node is required. It specifies the login name of a client template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

Request Samples
The following set request packet updates IP pool settings for two client templates which belong to Plesk Administrator, one template is specified by id, and another by name. Since the same filter node cannot use both id and name nodes, we use two different filter nodes (and two set operations):
<packet version=1.6.0.0> <client-template> <set> <filter> <id>12</id> </filter> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> <allocate-ip>2</allocate-ip> </ip-pool> <owner-login>admin</owner-login> </set> <set> <filter> <name>base_template</name> </filter> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> <allocate-ip>2</allocate-ip> </ip-pool> <owner-login>admin</owner-login></set></client-template></packet>

Supported Operations

159

The following packet updates all client templates belong to one Plesk user with similar IP pool settings:
<packet version=1.6.0.0> <client-template> <set> <filter/> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> </ip-pool> <owner-login>JDoe</owner-login> </set> </client-template> </packet>

The following packet will be considered invalid as it does not specify any settings:
<packet version=1.6.0.0> <client-template> <set> <filter> <id>12</id> </filter> <owner-id>3</owner-id> </set> </client-template> </packet>

To see sample packets setting up various client settings, refer to the Client Template Settings (see page 136)section.

160

Supported Operations

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ClientTemplateOutputResulttype (client_template.xsd). The status node is required. It specifies the execution status of the set operation. Data type: result_status (common.xsd). Allowed values: ok | error. The errcode node is required if the set operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the set operation fails. It returns the error message. Data type: string. The id node is required if the set operation succeeds. It returns the ID of the client template which settings were modified. Data type: integer. The name node is required if the set operation succeeds. It returns the name of the client template which settings were modified. Data type: string.

Supported Operations

161

Response Samples
A positive set response packet can look as follows:
<packet version=1.4.2.0> <client-template> <set> <result> <status>ok</status> <name>base_template</name> </result> <result> <status>ok</status> <id>12</id> </result> </set> </client-template> </packet>

The first template was filtered by name base_template, the second one was filtered by id 12. A negative set response packet looks as follows:
<packet version=1.4.2.0> <client-template> <set> <result> <status>ok</status> <name>base_template</name> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>12</id> </result> </set> </client-template> </packet>

The update of the first client template was successful, while the update of the second template failed.

162

Supported Operations

Managing Database Servers


Operator: <db_server> XML Schema: database_input.xsd, database_output.xsd Plesk version: Plesk for MS Windows 7.0, Plesk 7.5.4 for Unix and later API RPC version: 1.3.5.1 and higher Plesk user: Plesk Administrator Description

Managing database servers differs in Plesk for Unix and Plesk for Windows, basing on what databases are supported: Plesk for Windows supports MySQL and Microsoft SQL Server databases, Plesk for Unix supports MySQL and PostgreSQL databases.

A default database server is the one on which databases of a particular type are created by default, i.e., without specifying the parent database server. Only one default database server for each type of databases is available in Plesk.

Note: Use lower case for defining database servers types. In other case, the request might be incorrectly processed by Plesk server.

In this section:
Adding Database Server ................................................................................... 164 Changing Database Server Preferences ........................................................... 170 Detaching Database Servers ............................................................................. 175 Setting Default Database Server ....................................................................... 180 Retrieving Default Database Server Info ........................................................... 184 Retrieving Database Server Parameters ........................................................... 189 Retrieving Supported Types Of Databases ....................................................... 195 Retrieving Local Database Servers Info ............................................................ 198

Supported Operations

163

Supported operations

ADD (on page 164) creates a database server entry of the specified type, specifying the login and password of the database administrator. SET (on page 170) updates properties of the specified database server. DEL (on page 175) removes a database server entry. Only remote database servers can be specified. The default database server cannot be removed. SET-DEFAULT (on page 180) sets a remote database server entry as default for its DBMS type. Only remote database servers can be specified. GET-DEFAULT (on page 184) retrieves ID of a default database server. GET (on page 189) retrieves the database server info by the server ID. GET-SUPPORTED-TYPES (on page 195) get the DBMS types supported by the Plesk. GET-LOCAL (on page 198) retrieves ID of a local database server.

164

Supported Operations

Adding Database Server


The add operation is used to add a database server of the specified type to Plesk. Before adding the database server, make sure the database server type is supported by Plesk. For more information, refer to the Managing Database Server (on page 161) topic. Note: This operation is supported in Plesk for Windows since v.8.2 (API RPC protocol v.1.5.1.0).

In this section:
Request Packet Structure.................................................................................. 164 Request Samples .............................................................................................. 166 Response Packet Structure ............................................................................... 167 Response Samples ........................................................................................... 168

Request Packet Structure


A request XML packet adding a database server includes the add operation node:
<packet version="1.5.2.0"> <db_server> <add-db> </add-db> </db_server> </packet>

The add node is presented by type DatabaseServerAddParam (plesk_db.xsd), and its graphical representation is as follows:

The host node is required. It specifies the IP address or name of the database server you want to add. Data type: string.

Supported Operations

165

The port node is required. It specifies the port of the database server. Data type: string. The type node is required. It specifies the database server type. Data type: string. Allowed values: mysql | postgresql | mssql. The admin node is required. It specifies the login name of administrator of the database server. Data type: integer. The password node is optional. It specifies the password of administrator of the database server. Data type: integer. The default node is optional. It specifies if the database server manages the databases of a certain type (defined by type). Data type: none.

Note: The add operation is presented by type DatabaseServerDescription in API RPC v.1.3.5.1 Remarks You can add multiple database servers in a single packet. Add as many add operations as the number of database servers you want to add.
<db_server> <add> </add> ... <add> </add> </db_server>

166

Supported Operations

Request Samples
Adding a single database server This packet adds the local MySQL database server.
<packet version="1.5.2.0"> <db_server> <add> <host>localhost</host> <port>3306</port> <type>mysql</type> <admin>senior</admin> <password>senior</password> </add> </db_server> </packet>

This packet adds the default PostgreSQL database server.


<packet version="1.5.2.0"> <db_server> <add> <host>71.5.44.29</host> <port>3306</port> <type>postgresql</type> <admin>senior</admin> <password>senior</password> <default/> </add> </db_server> </packet>

Adding multiple database servers This request packet adds local MySQL and PostgreSQL database servers.
<packet version="1.5.2.0"> <db_server> <add> <host>localhost</host> <port>3306</port> <type>mysql</type> <admin>senior</admin> <password>senior</password> </add> <add> <host>localhost</host> <port>3307</port> <type>postgresql</type> <admin>senior</admin> <password>senior</password> </add> </db_server> </packet>

Supported Operations

167

Response Packet Structure


The add node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the add operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add operation fails. Data type: string. The id node is optional. If the add operation succeeds, it returns the ID of the database server. Data type: integer.

168

Supported Operations

Response Samples
Adding a single database server This request packet adds the local MySQL database server.
<packet version="1.5.2.0"> <db_server> <add> <host>localhost</host> <port>3306</port> <type>mysql</type> <admin>senior</admin> <password>senior</password> </add> </db_server> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <add> <result> <status>ok</status> <id>15</id> </result> </add> </db_server> </packet>

If the type of database server is not supported by Plesk, the response looks as follows:
<packet version="1.5.2.0"> <db_server> <add> <result> <status>error</status> <errcode>14008</errcode> <errtext>Wrong database server type</errtext> </result> </add> </db_server> </packet>

If the local MySQL database server already exists in Plesk, the response looks as follows:
<packet version="1.5.2.0"> <db_server> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed</errtext> </result> </add></db_server></packet>

Supported Operations

169

In API RPC 1.5.1.0 and later versions, if incorrect parameters were specified in the request packet, the error 1019 occurs. Adding multiple database servers This request packet adds local MySQL and PostgreSQL database servers.
<packet version="1.5.2.0"> <db_server> <add> <host>localhost</host> <port>3306</port> <type>mysql</type> <admin>senior</admin> <password>senior</password> </add> <add> <host>localhost</host> <port>3307</port> <type>postgresql</type> <admin>senior</admin> <password>senior</password> </add> </db_server> </packet>

If the MySQL server was successfully added, and PostgreSQL already exists in Plesk, a response from the server can look as follows:
<packet version="1.5.2.0"> <db_server> <add> <result> <status>ok</status> <id>15</id> </result> </add> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed</errtext> </result> </add> </db_server> </packet>

170

Supported Operations

Changing Database Server Preferences


Use the set operation to change preferences of the database server specified by ID. You can change preferences for multiple database servers in a single packet.

In this section:
Request Packet Structure.................................................................................. 170 Request Samples .............................................................................................. 171 Response Packet Structure ............................................................................... 172 Response Samples ........................................................................................... 173

Request Packet Structure


A request XML packet changing a database server preferences includes the set operation node:
<packet version="1..2.0"> <db_server> <set> </set> </db_server> </packet>

The set node is presented by type DatabaseServerDescriptionOpt (plesk_db.xsd) and has the following graphical representation:

The host node is required. It specifies new IP address or name of the database server. Data type: string. The port node is required. It specifies new port of the database server. Data type: string. The admin node is required. It specifies the login name of administrator of the database server. Data type: integer. The password node is optional. It specifies the password of the administrator of the database server. Data type: integer.

Supported Operations

171

The id node is required. It specifies the database server ID. Data type: integer.

Remarks You can change preferences for multiple database servers in a single packet. Add as many set operations as the number of database servers which preferences are to be changed.
<db_server> <set> </set> ... <set> </set> </db_server>

Request Samples
Changing preferences of a database server This packet changes IP address of the database server specified by ID 1.
<packet version="1.5.2.0"> <db_server> <set> <host>11.122.23.14</host> <port>3306</port> <admin>senior</admin> <password>senior</password> <id>1</id> </set> </db_server> </packet>

Changing preferences of multiple database servers This request packet changes ports of the MySQL and PostgreSQL database servers specified by ID 7 and ID 8.
<packet version="1.5.2.0"> <db_server> <set> <host>localhost</host> <port>336</port> <admin>senior</admin> <password>senior</password> <id>7</id> </set> <set> <host>localhost</host> <port>337</port> <admin>senior</admin> <password>senior</password> <id>8</id> </set> </db_server></packet>

172

Supported Operations

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set operation fails. Data type: string. The id node is optional. If the set operation succeeds, it returns the ID of the database server. Data type: integer.

Supported Operations

173

Response Samples
Changing preferences of a database server This packet changes IP address of the database server specified by ID 1.
<packet version="1.5.2.0"> <db_server> <set> <host>11.122.23.14</host> <port>3306</port> <admin>senior</admin> <password>senior</password> <id>1</id> </set> </db_server> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <db_server> <set> <result> <status>ok</status> <id>1</id> </result> </set> </db_server> </packet>

If the database server with ID 1 was not found on the server, the positive response looks as follows:
<packet version="1.5.2.0"> <db_server> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database server does not exist</errtext> </result> </set> </db_server> </packet>

174

Supported Operations

Changing preferences of multiple database servers This request packet changes ports of the MySQL and PostgreSQL database servers specified by ID 7 and ID 8.
<packet version="1.5.2.0"> <db_server> <set> <host>localhost</host> <port>336</port> <admin>senior</admin> <password>senior</password> <id>7</id> </set> <set> <host>localhost</host> <port>337</port> <admin>senior</admin> <password>senior</password> <id>8</id> </set> </db_server> </packet>

If preferences of the database server with ID 7 were successfully changed, and the database server with ID 8 was not found on the server, the response looks as follows:
<packet version="1.5.2.0"> <db_server> <set> <result> <status>ok</status> <id>7</id> </result> </set> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database server does not exist</errtext> </result> </set> </db_server> </packet>

Supported Operations

175

Detaching Database Servers


Use the del operation to detach database servers from Plesk. This option is available only for remote database servers. Default database servers cannot be removed using this operation. You can detach multiple database servers in a single packet. Note: This operation is supported in Plesk for Windows since v.8.2 (API RPC protocol v.1.5.1.0).

In this section:
Request Packet Structure.................................................................................. 175 Request Samples .............................................................................................. 176 Response Packet Structure ............................................................................... 177 Response Samples ........................................................................................... 178

Request Packet Structure


A request XML packet detaching a database server from Plesk includes the del operation node:
<packet version="1.4.2.0"> <db_server> <del> </del> </db_server> </packet>

The del node has the following graphical representation:

The filter node is required. Specifies the filtering rule. Data type: DatabaseServerFilterType (database_input.xsd). The id node is optional. It specifies ID of the database server to be detached. Data type: integer.

176

Supported Operations

Remarks You can detach multiple database servers from Plesk in a single packet. Add as many id parameters as the number of database servers which are to be detached.
<db_server> <del> <filter> <id>...</id> ... <id>...</id> </filter> </del> </db_server>

Request Samples
Unregistering a single database server This packet detaches the database server specified by ID 5 from Plesk.
<packet version="1.5.2.0"> <db_server> <del> <filter> <id>5</id> </filter> </del> </db_server> </packet>

Unregistering multiple database servers This packet detaches the database servers specified by ID 5 and ID 7 from Plesk.
<packet version="1.5.2.0"> <db_server> <del> <filter> <id>5</id> <id>7</id> </filter> </del> </db_server> </packet>

This packet detaches all remote database servers from Plesk.


<packet version="1.5.2.0"> <db_server> <del> <filter/> </del> </db_server> </packet>

Supported Operations

177

Response Packet Structure


The del node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the del operation fails. Data type: integer The errtext node is optional. It returns the error message if the del operation fails. Data type: string. The id node is optional. It returns the ID of the database server. Data type: integer.

178

Supported Operations

Response Samples
Unregistering a single database server This packet detaches the database server specified by ID 5 from Plesk.
<packet version="1.5.2.0"> <db_server> <del> <filter> <id>5</id> </filter> </del> </db_server> </packet>

The positive response from the server is as follows:


<packet version="1.5.2.0"> <db_server> <del> <result> <status>ok</status> <id>5</id> </result> </del> </db_server> </packet>

If the database server was a default database server, the response from the server looks as follows:
<packet version="1.5.2.0"> <db_server> <del> <result> <status>error</status> <errcode>1023</errcode> <errtext>The default database server cannot be deleted.</errtext> <id>5</id> </result> </del> </db_server> </packet>

Supported Operations

179

If the database server with ID 5 was not found on the server, the response looks as follows:
<packet version="1.5.2.0"> <db_server> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database server does not exist.</errtext> <id>5</id> </result> </del> </db_server> </packet>

Unregistering multiple database servers This packet detaches all remote database servers from Plesk.
<packet version="1.5.2.0"> <db_server> <del> <filter/> </del> </db_server> </packet>

Three database servers were detached from Plesk. A possible response from the server looks as follows:
<packet version="1.5.2.0"> <db_server> <del> <result> <status>ok</status> <id>5</id> </result> <result> <status>ok</status> <id>6</id> </result> <result> <status>ok</status> <id>7</id> </result> </del> </db_server> </packet>

180

Supported Operations

Setting Default Database Server


A default database server manages all databases of the corresponding type. Only one default database server for each type of databases is available in Plesk. Use the setdefault operation to set a database server as default. Note: This operation is supported in Plesk for Windows since v.8.2 (API RPC protocol v.1.5.1.0).

In this section:
Request Packet Structure.................................................................................. 180 Request Samples .............................................................................................. 181 Response Packet Structure ............................................................................... 182 Response Samples ........................................................................................... 183

Request Packet Structure


A request XML packet setting a default database server includes the set-default operation node:
<packet version="1.5.2.0"> <db_server> <set-default> </set-default> </db_server> </packet>

The set-default node has the following graphical representation:

The id node is required. It specifies the remote database server ID. Data type: integer. The type node is required. If specified, the local database server will be set as default for managing the databases of the specified type. Data type: string. Allowed values: mysql | postgresql | mssql.

Note: You can set only one default database server for each type of databases.

Supported Operations

181

Remarks You can set multiple database servers as default in a single packet. Add as many setdefault operations as the number of database servers which status is to be changed.
<db_server> <set-default> </set-default> ... <set-default> </set-default> </db_server>

Request Samples
Changing status of a database server Upon supposition that the type of remote database server with ID 1 is mysql, the following packet sets the database server as default for managing MySQL databases.
<packet version="1.5.2.0"> <db_server> <set-default> <id>1</id> </set-default> </db_server> </packet>

The following packet sets the local database server as default for managing MySQL databases.
<packet version="1.5.2.0"> <db_server> <set-default> <type>1</type> </set-default> </db_server> </packet>

Changing status of multiple database servers This packet sets the remote database server with ID 1 and local Microsoft SQL database server as default for MySQL and Microsoft SQL databases correspondingly.
<packet version="1.5.2.0"> <db_server> <set-default> <id>1</id> </set-default> <set-default> <type>mssql</type> </set-default> </db_server> </packet>

182

Supported Operations

Response Packet Structure


The set-default node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the set-default operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set-default operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set-default operation fails. Data type: string. The id node is optional. If the set-default operation succeeds and ID was specified in the request packet, it returns the ID of the database server. Data type: integer.

Supported Operations

183

Response Samples
Changing status of a database server Upon supposition that the type of remote database server with ID 1 is mysql, the following request packet sets the database server as default for managing MySQL databases.
<packet version="1.5.2.0"> <db_server> <set-default> <id>1</id> </set-default> </db_server> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <db_server> <set-default> <result> <status>ok</status> <id>1</id> </result> </set-default> </db_server> </packet>

If the database server with ID 1 was not found on the server, the response looks as follows:
<packet version="1.5.2.0"> <db_server> <set-default> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database server does not exist.</errtext> </result> </set-default> </db_server> </packet>

184

Supported Operations

Changing status of multiple database servers This packet sets the remote database server with ID 1 and local Microsoft SQL database server as default for MySQL and Microsoft SQL databases correspondingly.
<packet version="1.5.2.0"> <db_server> <set-default> <id>1</id> </set-default> <set-default> <type>mssql</type> </set-default> </db_server> </packet>

A response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <set-default> <result> <status>ok</status> <id>1</id> </result> </set-default> <set-default> <result> <status>ok</status> </result> </set-default> </db_server> </packet>

Retrieving Default Database Server Info


A default database server manages all databases of the corresponding type. Only one default database server for each type of databases is available in Plesk. Use the getdefault operation to retrieve a default database server. Note: This operation is supported in Plesk for Windows since v.8.2 (API RPC protocol v.1.5.1.0).

In this section:
Request Packet Structure.................................................................................. 185 Request Samples .............................................................................................. 186 Response Packet Structure ............................................................................... 186 Response Samples ........................................................................................... 187

Supported Operations

185

Request Packet Structure


A request XML packet retrieving a default database server info includes the get-default operation node:
<packet version="1.4.2.0"> <db_server> <get-default> </get-default> </db_server> </packet>

The get-default node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: none. The type node is required. It specified the default database of which type to retrieve. Data type: string. Allowed values: mysql | postgresql | mssql.

Note: If the filter node is left blank (<filter/>), the operation will return default database servers for all types of databases. A single packet can retrieve the data of multiple default database servers. Add as many different type parameters as the number of default database servers info on which you want to retrieve.

<db_server> <get-default> </get-default> ... <get-default> </get-default> </db_server>

186

Supported Operations

Request Samples
Retrieving status of a database server This packet retrieves default Microsoft SQL database server.
<packet version="1.5.2.0"> <db_server> <get-default> <filter> <type>mssql</type> </filter> </get-default> </db_server> </packet>

Retrieving status of multiple database servers This packet retrieves default MySQL and PostgreSQL database servers.
<packet version="1.5.2.0"> <db_server> <get-default> <filter> <type>mysql</type> <type>postgresql</type> </filter> </get-default> </db_server> </packet>

Response Packet Structure


The get-default node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd).

Supported Operations

187

The status node is required. It specifies the execution status of the get-default operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-default operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-default operation fails. Data type: string. The type node is optional. It returns the type of the database server. Data type: string. The id node is optional. If the get-default operation succeeds, it returns the ID of the database server. Data type: integer.

Note: In the API RPC 1.3.5.1 either id or type can be retrieved.

Response Samples
Retrieving status of a database server This request packet retrieves default Microsoft SQL database server info.
<packet version="1.5.2.0"> <db_server> <get-default> <filter> <type>mssql</type> </filter> </get-default> </db_server> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <get-default> <result> <status>ok</status> <type>mssql</type> <id>2l</id> </result> </get-default> </db_server> </packet>

188

Supported Operations

If an unsupported type was specified in the request packet, the response from the server looks as follows:
<packet version="1.5.2.0"> <db_server> <get-default> <result> <status>error</status> <status>14006</status> <status>unsupported database type</status> </result> </get-default> </db_server> </packet>

Retrieving status of multiple database servers This packet retrieves default MySQL and PostgreSQL database servers info.
<packet version="1.5.2.0"> <db_server> <get-default> <filter> <type>mysql</type> <type>postgresql</type> </filter> </get-default> </packet>

A possible response from the server looks as follows:


<packet version="1.5.2.0"> <db_server> <get-default> <result> <status>ok</status> <type>mysql</type> <id>2l</id> </result> <result> <status>ok</status> <type>postgresql</type> <id>1l</id> </result> </get-default> </db_server> </packet>

Supported Operations

189

Retrieving Database Server Parameters


Use get operation to retrieve parameters of the database server specified by ID. You can retrieve preferences of multiple database servers in a single operation.

In this section:
Request Packet Structure.................................................................................. 189 Request Samples .............................................................................................. 190 Response Packet Structure ............................................................................... 191 Response Samples ........................................................................................... 193

Request Packet Structure


A request XML packet retrieving a database server info includes the get operation node:
<packet version="1.5.2.0"> <db_server> <get> </get> </db_server> </packet>

The get node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: none. The id node is optional. Specifies the database server ID. Data type: integer.

Note: If the filter node is left blank (<filter/>), the operation will return info on all database servers. Remarks A single operation can retrieve the data of multiple database servers. Add as many different id parameters as the number of database servers info on which you want to retrieve.
<db_server> <get> </get> ... <get> </get> </db_server>

190

Supported Operations

Request Samples
Retrieving a single database server This packet retrieves info on the database server specified by ID 7.
<packet version="1.5.2.0"> <db_server> <get> <filter> <id>7</id> </filter> </get> </db_server> </packet>

Retrieving multiple database servers This packet retrieves info on database servers specified by ID 7 and ID 9.
<packet version="1.5.2.0"> <db_server> <get> <filter> <id>7</id> <id>9</id> </filter> </get> </db_server> </packet>

This packet retrieves info on all database servers available for the packet sender.
<packet version="1.5.2.0"> <db_server> <get> <filter/> </get> </db_server> </packet>

Supported Operations

191

Response Packet Structure


The get node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: extension of DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. The id node is optional. It returns the ID of the database server. Data type: integer.

192

Supported Operations

The data node is optional. Data type: databaseServerDescription (plesk_db.xsd) If the get operation succeeded it returns the following data: The host node is optional. Specifies the IP address or name of the database server. Data type: string. The port node is optional. It specifies the port of the database server. Data type: string. The type node is required. It returns the type of the database server. Data type: string. The admin node is required. It specifies the login name of administrator of the database server. Data type: integer. The password node is optional. It specifies the password of the administrator of the database server. Data type: integer. The status node is required. It specifies the status of connection to the database server. Data type: string. Allowed values: NO_ERROR | CONNECTION_FAILED | LOGIN_FAILED | PERMISSION_DENIED | OTHER_ERROR | CREDENTIALS_NOT_SET The db_num node is required. It specifies the number of databases managed by the database server. Data type: integer. The default node is optional. It specifies a default database server. Data type: none.

The local node is optional. It specifies a local database server. Data type: none.

Supported Operations

193

Response Samples
Retrieving a single database server This packet retrieves the database server specified by ID 7
<packet version="1.5.2.0"> <db_server> <get> <filter> <id>7</id> </filter> </get> </db_server> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <get> <result> <status>ok</status> <id>7</id> <data> <host>14.13.11.2</host> <port>5432</port> <type>mysql</type> <admin></admin> <status>CREDENTIALS_NOT_SET</status> <db_num>0</db_num> </data> </result> </get> </db_server> </packet>

If the database server was not found, the result is as follows:


<packet version="1.5.2.0"> <db_server> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database server does not exist.</errtext> </result> </get> </db_server> </packet>

194

Supported Operations

Retrieving multiple database servers This request packet retrieves info on the database servers specified by ID 2 and ID 92.
<packet version="1.5.2.0"> <db_server> <get> <filter> <id>2</id><id>92</id> </filter> </get> </db_server> </packet>

A possible response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <get> <result> <status>ok</status> <id>2</id> <data> <host>localhost</host> <port>5432</port> <type>postgresql</type> <admin></admin> <status>CREDENTIALS_NOT_SET</status> <db_num>0</db_num> <default></default> <local></local> </data> </result> <result> <status>ok</status> <id>92</id> <data> <host>some.host</host> <port>5432</port> <type>postgresql</type> <admin>admin</admin> <password>qweqwe</password> <status>OTHER_ERROR</status> <db_num>0</db_num> </data> </result> </get> </db_server> </packet>

Supported Operations

195

Retrieving Supported Types Of Databases


A request XML packet retrieving types of database servers supported by Plesk includes the get-supported-types operation node:
<packet version="1.5.2.0"> <dns> <get-supported-types/> </dns> </packet>

The graphical representation of the get-supported-types node is as follows:

Request sample This request packet retrieves the supported types of database servers.
<packet version="1.5.2.0"> <db_server> <get-supported-types/> </db_server> </packet>

In this section:
Response Packet Structure ............................................................................... 196 Response Samples ........................................................................................... 197

196

Supported Operations

Response Packet Structure


The get-supported-types node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the get-supportedtypes operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-supported-types operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-supported-types operation fails. Data type: string. The type node is optional. It returns the types of supported database servers if the get-supported-types operation succeeds. Data type: string.

Supported Operations

197

Response Samples
This request packet retrieves the supported types of database servers.
<packet version="1.5.2.0"> <db_server> <get-supported-types/> </db_server> </packet>

If the request was sent to Plesk for MS Windows server, the result is as follows:
<packet version="1.5.2.0"> <db_server> <get-supported-types> <result> <status>ok</status> <type>mssql</type> <type>mysql</type> </result> </get-supported-types> </db_server> </packet>

If the request was sent to Plesk for Unix server, the result is as follows:
<packet version="1.5.2.0"> <db_server> <get-supported-types> <result> <status>ok</status> <type>mysql</type> <type>postgresql</type> </result> </get-supported-types> </db_server> </packet>

198

Supported Operations

Retrieving Local Database Servers Info


Use the get-local operation to retrieve info on local database servers of the specified type. You can retrieve preferences of multiple local database servers in a single packet. Note: This operation is supported in Plesk for Windows since v.8.2 (API RPC protocol v.1.5.1.0).

In this section:
Request Packet Structure.................................................................................. 198 Request Samples .............................................................................................. 199 Response Packet Structure ............................................................................... 200 Response Samples ........................................................................................... 200

Request Packet Structure


A request XML packet retrieving a local database server info includes the get-local operation node:
<packet version="1.4.2.0"> <db_server> <get-local> </get-local> </db_server> </packet>

The get-local node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: none. The type node is optional. It specifies the type of local database servers. Data type: string. Allowed values: mssql | mysql | postgresql.

Note: If the filter node is left blank (<filter/>), the operation will return info on all local database servers.

Supported Operations

199

A single operation can retrieve the data of multiple database servers. Add as many different type parameters as the number of local database servers info on which you want to retrieve.
<db_server> <get-local> </get-local> ... <get-local> </get-local> </db_server>

Request Samples
Retrieving info on a single database server This packet retrieves info on the local MySQL database server.
<packet version="1.5.2.0"> <db_server> <get-local> <filter> <type>mysql</type> </filter> </get-local> </db_server> </packet>

Retrieving info on multiple database servers This packet retrieves info on all local database servers.
<packet version="1.5.2.0"> <db_server> <get-local> <filter/> </get-local> </db_server> </packet>

200

Supported Operations

Response Packet Structure


The get-local node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DatabaseServerResultType (database_output.xsd). The status node is required. It specifies the execution status of the get-local operation. Data type: string. Allowed values: ok | error. The errtext node is optional. It returns the error message if the get-local operation fails. Data type: string. The errcode node is optional. Is returns the error code if the get-local operation fails. Data type: integer. The type node is required. It returns the type of the database server. Data type: string. The id node is optional. It returns the ID of the database server. Data type: integer.

Note: In the API RPC 1.3.5.1 either id or type can be retrieved.

Response Samples
Retrieving info on a single database server This request packet retrieves info on the MySQL local database server.
<packet version="1.5.2.0"> <db_server> <get-local> <filter> <type>mysql</type> </filter> </get-local> </db_server> </packet>

Supported Operations

201

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <get-local> <result> <status>ok</status> <type>mysql</type> <id>1</id> </result> </get-local> </db_server> </packet>

If the type of database server was invalid, the response from the server looks as follows:
<packet version="1.5.2.0"> <db_server> <get-local> <result> <status>error</status> <errcode>14007</errcode> <errtext>Unsupported database type</errtext> <type>NewSQL</type> </result> </get-local> </db_server> </packet>

Retrieving info on multiple database servers This request packet retrieves info on all local database servers.
<packet version="1.5.2.0"> <db_server> <get-local> <filter/> </get-local> </db_server> </packet>

202

Supported Operations

A possible response from the server can look as follows:


<packet version="1.5.2.0"> <db_server> <get-local> <result> <status>ok</status> <type>mysql</type> <id>1</id> </result> <result> <status>ok</status> <type>postgresql</type> <id>2</id> </result> </get-local> </db_server> </packet>

Managing Databases
Operator: <database> XML Schema: database_input.xsd, database_output.xsd Plesk version: Plesk 8.1 for Windows | Plesk 8.1 for Unix API RPC version: 1.4.2.0 and higher Plesk user: Plesk Administrator, Plesk client Description Databases are used to store information in a tables format. You can add users to a database (create their own accounts) to grant them access to this information. One of the database user accounts (hereinafter referred to as database administrator) is used for administering the database via the Plesk graphical user interface (DB WebAdmin tool) or by connecting directly to the database server.

In this section:
Filtering Issues .................................................................................................. 204 Creating Databases........................................................................................... 205 Deleting Databases ........................................................................................... 211 Creating Database Users .................................................................................. 215 Assigning Database Administrator..................................................................... 221 Retrieving Database Administrator Info ............................................................. 224 Retrieving Information About Databases ........................................................... 230 Changing Database User Credentials ............................................................... 237 Retrieving Database Users Info ......................................................................... 242 Deleting Database Users................................................................................... 246

Supported Operations

203

Supported operations

ADD-DB (see page 205) creates database entry of the specified type, defining the domain that will use it DEL-DB (see page 211) removes database entry; If a database is used by an application installed on the server, it cannot be removed GET-DB (see page 230) retrieves database parameters by the ID, domain name or domain ID SET-DEFAULT-USER (see page 221) specifies a database administrator GET-DEFAULT-USER (see page 224) retrieves ID of administrator of a specified database ADD-DB-USER (see page 215) creates a database user account for a specified database DEL-DB-USER (see page 246) removes a database user account from a specified database GET-DB-USERS (see page 242) retrieves the list of users of a specified database SET-DB-USER (see page 237) changes credentials of a database user

Remarks Before working with databases, be sure to call operation get_supported_types (on page 195) or the db_server (on page 161) operator in order to retrieve information on which database servers are configured on the specific Plesk server.

204

Supported Operations

Filtering Issues
Filtering is the way the request XML packet indicates the object to which the operation will be applied. The request XML filters data using a special <filter> section. A single filter can specify multiple database users, all specified either by ID or by database ID. It also can match multiple databases, specified either by ID, domain ID, or domain name. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.
<filter> ... </filter>

A packet that retrieves information about databases on domain MyDomain.com can look as follows:
<packet version="1.4.2.0"> <database> <get-db> <filter> <domain-name>MyDomain.com</domain-name> </filter> </get-db> </database> </packet>

If an operation in a request packet (del-db-user, get-db, get-db-users, get-default-user, deldb) uses filters, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet: database ID domain name domain ID database user ID

It is done so to trace the request parameters in case of an error. Data type: anySimple. If the filter node is left blank (<filter/>), the filter-id parameter will hold the ID of the object. The blank filter means that all objects (like databases or database users) are matched by this rule. Note: The <filter-id> node appears in API RPC 1.4.2.0. Earlier versions of the protocol do not support this node.

Supported Operations

205

Creating Databases
The add-db operation is used to create a database for a certain domain. You can specify the database settings only on creation. You can create a database of one of the following types: MySQL or MS SQL in Plesk for Windows MySQL or PostgreSQL in Plesk for Unix

In this section:
Request Packet Structure ..................................................................................205 Request Samples ..............................................................................................206 Response Packet Structure ...............................................................................208 Response Samples ............................................................................................209

Request Packet Structure


A request XML packet creating a database includes the add-db operation node:
<packet version="1.4.2.0"> <database> <add-db> </add-db> </database> </packet>

The add-db node is presented by type DatabaseAddInputType (database_input.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain on which you want to create database. Data type: integer. The name node is required. It specifies the database name. Data type: string. The type node is required. It specifies the database type. MySQL and MS SQL are available in Plesk for Windows. MySQL and PostgreSQL types are available in Plesk for Unix. Data type: string.

206

Supported Operations

The db-server-id node is required. It specifies the ID of the database server on which the database will be created. This node is required only in Plesk for Unix. Data type: integer.

Note: The db-server-id node is required only when you use Plesk for Unix. For info on database servers, refer to Managing Database Servers (on page 161) section. In Plesk for Windows, you can define the ID of a database server by the type of databases. However, it is recommended to consider this parameter as required, because in next versions of Plesk for Windows the algorithm of defining database servers can be changed. Note: Use lower case for the database types. In other case the request might be incorrectly processed by the server. Remarks You can add multiple databases in a single packet. Add as many add-db operations as the number of databases you want to add.
<database> <add-db> </add-db> ... <add-db> </add-db> </database>

Request Samples
Adding a database This packet adds MyBase MySQL database to the domain specified by ID 7. The packet is valid only in Plesk for Windows.
<packet version="1.4.2.0"> <database> <add-db> <domain-id>7</domain-id> <name>MyBase</name> <type>mysql</type> </add-db> </database> </packet>

Supported Operations

207

This packet adds My2Base PostgreSQL database to the domain specified by ID 8. This example is valid only in Plesk for Unix.
<packet version="1.4.2.0"> <database> <add-db> <domain-id>7</domain-id> <name>My2Base</name> <type>postgresql</type> <db-server-id>34</db-server-id> </add-db> </database> </packet>

Adding multiple databases This packet adds two MySQL databases to the domain with ID 3. The packet is valid only in Plesk for Windows.
<packet version="1.4.2.0"> <database> <add-db> <domain-id>3</domain-id> <name>MyBase</name> <type>mysql</type> </add-db> <add-db> <domain-id>3</domain-id> <name>My2Base</name> <type>mysql</type> </add-db> </database> </packet>

208

Supported Operations

Response Packet Structure


The add-db node of the output XML packet is presented by type DatabaseAddDBOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add-db operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add-db operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add-db operation fails. Data type: string. The id node is optional. If the add-db operation succeeds, it returns the ID of the database. Data type: integer.

Supported Operations

209

Response Samples
Adding a database The request packet structured as follows:
<packet version="1.4.2.0"> <database> <add-db> <domain-id>7</domain-id> <name>MyBase</name> <type>mysql</type> </add-db> </database> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <database> <result> <add-db> <status>ok</status> <id>14</id> </add-db> </result> </database> </packet>

If MyBase already exists, the response from the server looks as follows:
<packet version="1.4.2.0"> <database> <result> <add-db> <status>error</status> <errcode>1007</errcode> <errtext>Database already exists</errtext> </add-db> </result> </database> </packet>

210

Supported Operations

If the domain with ID 7 was not found, the response looks as follows:
<packet version="1.4.2.0"> <database> <result> <add-db> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> </add-db> </result> </database> </packet>

Adding multiple databases The request packet adding mySQL and PostgreSQL databases looks as follows:
<packet version="1.4.2.0"> <database> <add-db> <domain-id>3</domain-id> <name>MyBase</name> <type>mysql</type> </add-db> <add-db> <domain-id>3</domain-id> <name>MyBase</name> <type>mysql</type> </add-db> </database> </packet>

A possible response from the server looks as follows:


<packet version="1.4.2.0"> <database> <result> <add-db> <status>ok</status> <id>14</id> </add-db> </result> <result> <add-db> <status>error</status> <errcode>1007</errcode> <errtext>Database already exists</errtext> </add-db> </result> </database> </packet>

Supported Operations

211

Deleting Databases
Use the del-db operation to remove one or more databases.

In this section:
Request Packet Structure.................................................................................. 211 Request Samples .............................................................................................. 212 Response Packet Structure ............................................................................... 213 Response Samples ........................................................................................... 214

Request Packet Structure


A request XML packet deleting a database includes the del-db operation node:
<packet version="1.4.2.0"> <database> <del-db> </del-db> </database> </packet>

The del-db node is presented by type DatabaseDelDbInputType (database_input.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For information on filters, refer to the Filtering Issues (see page 204) section. Data type: DatabaseFilterType.

Note: If the filter node is blank, all databases are removed. The id node is optional. It specifies the ID of a database. Data type: integer. The domain-id node is optional. It specifies the ID of the domain on which databases are removed. Data type: integer.

212

Supported Operations

The domain-name node is optional. It specifies the name of the domain on which databases are removed. Data type: string (Unicode).

Remarks In API RPC 1.5.0.0 and earlier versions, the get-db node is presented by type DatabaseGetDBInputType.

Request Samples
Deleting a database This packet deletes the database with ID 55
<packet version="1.4.2.0"> <database> <del-db> <filter> <db-id>55</db-id> </filter> </del-db> </database> </packet>

Deleting multiple databases This packet deletes all databases from all database servers available for the packet sender identified by credentials from HTTP header.
<packet version="1.4.2.0"> <database> <del-db> <filter/> </del-db> </database> </packet>

This packet deletes databases with ID 67 and ID 16.


<packet version="1.4.2.0"> <database> <del-db> <filter> <db-id>67</db-id> <db-id>16</db-id> </filter> </del-db> </database> </packet>

Supported Operations

213

Response Packet Structure


The del-db node of the output XML packet is presented by type DatabaseDelDBOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the del-db operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the del-db operation fails. Data type: integer. The errtext node is optional. It returns the error message if the del-db operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 204) section. The id node is optional. If the add-db operation succeeds it returns the ID of the database.

214

Supported Operations

Response Samples
Deleting database The request packet looks as follows:
<packet version="1.4.2.0"> <database> <del-db> <filter> <db-id>55</db-id> </filter> </del-db> </database> </packet>

Positive response from the server can look as follows:


<packet version="1.4.2.0"> <database> <del-db> <result> <status>ok</status> <filter-id>55</filter-id> <id>55</id> </result> </del-db> </database> </packet>

Negative response from the server can look as follows:


<packet version="1.4.2.0"> <database> <del-db> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database does not exist</errtext> <filter-id>55</filter-id> </result> </del-db> </database> </packet>

Supported Operations

215

Deleting multiple databases The request packet looks as follows:


<packet version="1.4.2.0"> <database> <del-db> <filter/> </del-db> <del-db> <filter> <db-id>15</db-id> </filter> </del-db> </database> </packet>

A response from the server can look as follows:


<packet version="1.4.2.0"> <database> <del-db> <result> <status>ok</status> <filter-id>15</filter-id> <id>15</id> </result> <result> <status>ok</status> <filter-id>43</filter-id> <id>43</id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database does not exist</errtext> <filter-id>15</filter-id> </result> </del-db> </database> </packet>

The last result shows error, because the database with ID 15 is already deleted.

216

Supported Operations

Creating Database Users


You can create new user accounts for a certain database. Specify the user login name, password and the ID of the database where you want to create new user account. You can add multiple users to the database in a single packet.

In this section:
Request Packet Structure.................................................................................. 216 Request Samples .............................................................................................. 217 Response Packet Structure ............................................................................... 218 Response Samples ........................................................................................... 219

Request Packet Structure


A request XML packet creating database user account for the database includes the add-db-user operation node:
<packet version="1.4.2.0"> <database> <add-db-user> </add-db-user> </database> </packet>

The add-db-user node is presented by type DatabaseAddDBUserInputType (database_input.xsd), and its graphical representation is as follows:

The db-id node is required. It specifies ID of the database where a new user will be created. Data type: integer. The login node is required. It specifies login name of the database user. Data type: string. The password node is required. It specifies the password of the database user. Data type: string (length should be more than five digits). The password-type node is optional. Specifies if it is plain or encrypted password. Data type:string. Allowed values: plain | crypt.

Supported Operations

217

Remarks You can add multiple users to database in a single packet. Add as many add-db-user operations to the packet as the number of different users you want to create. You can also add multiple users to multiple databases in a single packet.
<database> <add-default-user> </add-default-user> ... <add-default-user> </add-default-user> </database>

Request Samples
Creating a database user This packet creates user MyUser on the database with ID 55.
<packet version="1.4.2.0"> <database> <add-db-user> <db-id>55</db-id> <login>MyUser</login> <password>hello</password> </add-db-user> </database> </packet>

Creating multiple database users This packet creates users MyUser and My2User on the database with ID 55.
<packet version="1.4.2.0"> <database> <add-db-user> <db-id>55</db-id> <login>MyUser</login> <password>hello</password> </add-db-user> <add-db-user> <db-id>55</db-id> <login>My2User</login> <password>123456</password> </add-db-user> </database> </packet>

218

Supported Operations

This packet creates users MyUser and My2User on the databases with ID 55 and ID 57.
<packet version="1.4.2.0"> <database> <add-db-user> <db-id>55</db-id> <login>MyUser</login> <password>hello</password> </add-db-user> <add-db-user> <db-id>55</db-id> <login>My2User</login> <password>123456</password> </add-db-user> <add-db-user> <db-id>57</db-id> <login>MyUser</login> <password>hello</password> </add-db-user> <add-db-user> <db-id>57</db-id> <login>My2User</login> <password>123456</password> </add-db-user> </database> </packet>

Response Packet Structure


The add-db--user node of the output XML packet is presented by type DatabaseAddDBUserOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add-db--user operation. Data type: string. Allowed values: ok | error.

Supported Operations

219

The errcode node is optional. Is returns the error code if the add-db--user operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add-db--user operation fails. Data type: string. The id node is required. It specifies the database user ID. Data type: integer.

Response Samples
Creating a database user This request packet creates user MyUser on the database with ID 55.
<packet version="1.4.2.0"> <database> <add-db-user> <db-id>55</db-id> <login>MyUser</login> <password>hello</password> </add-db-user> </database> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <database> <add-db-user> <result> <status>ok</status> <id>132</id> </result> </add-db-user> </database> </packet>

If the database was not found, the response looks as follows:


<packet version="1.4.2.0"> <database> <add-db-user> <result> <status>error</status> <errcode>1015</errcode> <errtext>Database not found</errtext> </result> </add-db-user> </database> </packet>

220

Supported Operations

If the login name is already used by another user account on this database, the response looks as follows:
<packet version="1.4.2.0"> <database> <add-db-user> <result> <status>error</status> <errcode>1007</errcode> <errtext>User already exists</errtext> </result> </add-db-user> </database> </packet>

Creating multiple database users This packet creates user MyUser on the databases with ID 55 and ID 57.
<packet version="1.4.2.0"> <database> <add-db-user> <db-id>55</db-id> <login>MyUser</login> <password>hello</password> </add-db-user> <add-db-user> <db-id>55</db-id> <login>My2User</login> <password>123456</password> </add-db-user> </database> </packet>

If the first operation succeeded and the database with ID=57 was not found, the response from the server looks as follows:
<packet version="1.4.2.0"> <database> <add-db-user> <result> <status>ok</status> <id>132</id> </result> </add-db-user> <add-db-user> <result> <status>error</status> <errcode>1015</errcode> <errtext>Database not found</errtext> </result> </add-db-user> </database> </packet>

Supported Operations

221

Assigning Database Administrator


Database administrator is a database user who can manage the database either via Plesk graphical user interface (DB WebAdmin tool) or by connecting directly to the database server. You can set any database user account as the database administrator's account. There can be only one administrator's account for each database. If you create a database, the first user created in the database will be appointed to act as a database administrator.

In this section:
Request Packet Structure.................................................................................. 221 Request Samples .............................................................................................. 222 Response Packet Structure ............................................................................... 222 Response Samples ........................................................................................... 223

Request Packet Structure


A request XML packet assigning a database administrator includes the set-default-user operation node:
<packet version="1.4.2.0"> <database> <set-default-user> </set-default-user> </database> </packet>

The set-default-user node is presented by type DatabaseSetDBInputType (database_input.xsd), and its graphical representation is as follows:

The db-id node is required. Specifies the database that will be managed by database administrator. Data type: integer. The default-user-id node is optional. Specifying the database administrator for managing a database. Data type: integer.

222

Supported Operations

Remarks You can set database administrators for multiple databases using a single packet. Add as many set-default-user operations as the number of database administrator's accounts you want to set.
<database> <set-default-user> </set-default-user> ... <set-default-user> </set-default-user> </database>

Request Samples
Assigning a Database Administrator This packet sets the user with ID 35 as administrator for the database with ID 132.
<packet version="1.4.2.0"> <database> <set-default-user> <db-id>132</db-id> <default-user-id>35</default-user-id> </set-default-user> </database> </packet>

Response Packet Structure


The set-default-user node of the output XML packet is presented by type DatabaseSetDBOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).

Supported Operations

223

The status node is required. It specifies the execution status of the set-default-user operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set-default-user operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set-default-user operation fails. Data type: string.

Response Samples
Assigning a Database Administrator This request packet sets the user with ID 35 as administrator for the database with ID 132.
<packet version="1.4.2.0"> <database> <set-default-user> <db-id>132</db-id> <default-user-id>35</default-user-id> </set-default-user> </database> </packet>

The negative response from the server looks as one of the follows: The database with ID=132 was not found on the server.

<packet version="1.4.2.0"> <database> <set-default-user> <result> <status>error</status> <errcode>1015</errcode> <errtext>Database not found</errtext> </result> </set-default-user> </database> </packet>

The user with ID=35 was not found in the database with ID=132.

<packet version="1.4.2.0"> <database> <set-default-user> <result> <status>error</status> <errcode>1015</errcode> <errtext>Database not found</errtext> </result> </set-default-user> </database> </packet>

224

Supported Operations

The positive response received from the server looks as follows:


<packet version="1.4.2.0"> <database> <set-default-user> <result> <status>ok</status> </result> </set-default-user> </database> </packet>

Retrieving Database Administrator Info


Administering database is available when using database administrator credentials, either via Plesk graphical user interface (DB WebAdmin tool) or by connecting directly to the database server. You can set any database user account as the database administrator's account. There can be only one administrator's account for each database. If you create a new database, the first user created in the database will be set as its administrator.

In this section:
Request Packet Structure.................................................................................. 225 Request Samples .............................................................................................. 226 Response Packet Structure ............................................................................... 227 Response Samples ........................................................................................... 228

Supported Operations

225

Request Packet Structure


A request XML packet retrieving database administrator info includes the get-default-user operation node:
<packet version="1.4.2.0"> <database> <get-default-user> </get-default-user> </database> </packet>

The get-default-user node is presented by type DatabaseGetDBInputType (database_input.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (see page 204) section. Data type: DatabaseDefaultUserFilterType. The db-id node is optional. It specifies ID of a database. Data type: integer.

Remarks You can retrieve ID's of multiple database administrators using a single packet. Add the get-default-user operation for each database to the request packet.
<database> <get-default-user> </get-default-user> ... <get-default-user> </get-default-user> </database>

226

Supported Operations

Request Samples
Retrieving info on a Database Administrator This packet retrieves info on administrator for the database with ID 35.
<packet version="1.4.2.0"> <database> <get-default-user> <filter> <db-id>35</db-id> </filter> </get-default-user> </database> </packet>

Retrieving info on multiple Database Administrators This packet retrieves administrators for all databases on all database servers available for the packet sender.
<packet version="1.4.2.0"> <database> <get-default-user> <filter/> </get-default-user> </database> </packet>

Supported Operations

227

Response Packet Structure


The get-default-user node of the output XML packet is presented by type DatabaseGetDefaultUserOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get-default-user operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-default-user operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-default-user operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 204) section. The id node is required. It specifies the database administrator ID. Data type: integer.

228

Supported Operations

Response Samples
Retrieving info on a Database Administrator This packet retrieves a Database Administrator of the database with ID 35.
<packet version="1.4.2.0"> <database> <get-default-user> <filter> <db-id>35</db-id> </filter> </get-default-user> </database> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <database> <get-default-user> <result> <status>ok</status> <filter-id>35</filter-id> <id>77</id> </result> </get-default-user> </database> </packet>

A negative response got from the server can look as follows:


<packet version="1.4.2.0"> <database> <get-default-user> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database not found</errtext> </result> </get-default-user> </database> </packet>

Supported Operations

229

Retrieving info on multiple Database Administrators This packet retrieves Database Administrators of all databases on all database servers available for the packet sender.
<packet version="1.4.2.0"> <database> <get-default-user> <filter/> </get-default-user> </database> </packet>

A response packet from the server can look as follows:


<packet version="1.4.2.0"> <database> <get-default-user> <result> <status>ok</status> <filter-id>15</filter-id> <id>77</id> </result> <result> <status>ok</status> <filter-id>35</filter-id> <id>17</id> </result> <result> <status>ok</status> <filter-id>24</filter-id> <id>72</id> </result> </get-default-user> </database> </packet>

230

Supported Operations

Retrieving Information About Databases


Use the get-db operation to retrieve the following database preferences: name type domain ID database server ID Database Administrator ID

In this section:
Request Packet Structure.................................................................................. 230 Request Samples .............................................................................................. 231 Response Packet Structure ............................................................................... 233 Response Samples ........................................................................................... 234

Request Packet Structure


A request XML packet retrieving database parameters includes the get-db operation node:
<packet version="1.4.2.0"> <database> <get-db> </get-db> </database> </packet>

The get-db node is presented by type DatabaseGetDBInputType (database_input.xsd), and its graphical representation is as follows:

Supported Operations

231

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (see page 204) section. Data type: DatabaseFilterType (database_input.xsd). The id node is optional. It specifies the ID of a database. Data type: integer. The domain-id node is optional. It specifies the ID of the domain on which a database is added. Data type: integer. The domain-name node is optional. It specifies the name of the domain on which a database is added. Data type: string (Unicode).

Remarks In API RPC 1.5.0.0 and earlier versions, the get-db node is presented by type DatabaseDelDbInputType (database_input.xsd). You can retrieve information on multiple databases using a single packet. Add as many get-db operations as the number of different filtering rules (you can either filter by ID, domain-id, or by domain-name).
<database> <get-db> <filter> ... </filter> </get-db> </database>

Request Samples
Retrieving database parameters This packet retrieves information about a database with ID 5.
<packet version="1.4.2.0"> <database> <get-db> <filter> <id>5</id> </filter> </get-db> </database> </packet>

232

Supported Operations

Retrieving parameters of multiple databases This packet retrieves information on all databases added to domain MyDomain.com, and to the domain specified by ID 45.
<packet version="1.4.2.0"> <database> <get-db> <filter> <domain-name>MyDomain.com</domain-name> </filter> </get-db> <get-db> <filter> <domain-id>45</domain-id> </filter> </get-db> </database> </packet>

This packet retrieves information about all databases added to the MyDomain.com and My2Domain.com domains.
<packet version="1.4.2.0"> <database> <get-db> <filter> <domain-name>MyDomain.com</domain-name> <domain-name>My2Domain.com</domain-name> </filter> </get-db> </database> </packet>

This packet is wrong because it uses both domain-name and domain-id in one filter node.
<packet version="1.4.2.0"> <database> <get-db> <filter> <domain-name>MyDomain.com</domain-name> <domain-id>117</domain-id> </filter> </get-db> </database> </packet>

Supported Operations

233

Response Packet Structure


The get-db node of the output XML packet is presented by type DatabaseGetDBOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get-db operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-db operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-db operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 204) section. The name node is required. It specifies the database name. Data type: string. The type node is required. It specifies the database type. MySQL and MS SQL are available in Plesk for Windows. MySQL and PostgreSQL types are available in Plesk for Unix. Data type: string. Allowed values: mssql | mysql | postgresql.

234

Supported Operations

The domain-id node is optional. It is required if the get-db operation succeeds. It specifies the ID of the domain on which a database is added. Data type: integer. The db-server-id node is optional. It is required if the get-db operation succeeds. It specifies the ID of the database server on which a database will be created. This node is required only in Plesk for Unix. Data type: integer. The default-user-id node is optional. It is required if the get-db operation succeeds. It specifies ID of the database administrator. Data type: integer.

Response Samples
Retrieving database parameters This packet retrieves information on a database with ID 5.
<packet version="1.4.2.0"> <database> <get-db> <filter> <id>5</id> </filter> </get-db> </database> </packet>

Positive response from the server looks as follows:


<packet version="1.4.2.0"> <database> <get-db> <result> <status>ok</status> <filter-id>5</filter-id> <id>5</id> <name>MyDatabase</name> <type>mysql</type> <domain-id>77</domain-id> <db-server-id>17</db-server-id> <default-user-id>10</default-user-id> </result> </get-db> </database> </packet>

Supported Operations

235

Negative response from the server looks as follows:


<packet version="1.4.2.0"> <database> <get-db> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database does not exist</errtext> <filter-id>5</filter-id> </result> </get-db> </database> </packet>

Retrieving parameters of multiple databases This packet retrieves information on all databases added to the MyDomain.com, My2Domain.com domains and to the domain specified by ID 45.
<packet version="1.4.2.0"> <database> <get-db> <filter> <domain-name>MyDomain.com</domain-name> <domain-name>My2Domain.com</domain-name> </filter> </get-db> <get-db> <filter> <domain-id>45</domain-id> </filter> </get-db> </database> </packet>

One database was found on domain MyDomain.com, the domain with ID 45 and domain My2domain.com were not found. The response from the server in this case looks as follows:
<packet version="1.4.2.0"> <database> <get-db> <result> <status>ok</status> <filter-id>MyDomain.com</filter-id> <id>5</id> <name>MyDatabase</name> <type>mysql</type> <domain-id>77</domain-id> <db-server-id>17</db-server-id> <default-user-id>10</default-user-id> </result> </get-db>

236

Supported Operations <get-db> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>My2Domain.com</filter-id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>45</filter-id> </result> </get-db> </database> </packet>

When two or more databases are found on the specified domain, a server response is the following:
<packet version="1.4.2.0"> <database> <get-db> <result> <status>ok</status> <filter-id>MyDomain.com</filter-id> <id>5</id> <name>MyDatabase</name> <type>mysql</type> <domain-id>77</domain-id> <db-server-id>17</db-server-id> <default-user-id>10</default-user-id> </result> </get-db> <get-db> <result> <status>ok</status> <filter-id>MyDomain.com</filter-id> <id>8</id> <name>My2base</name> <type>mysql</type> <domain-id>77</domain-id> <db-server-id>17</db-server-id> <default-user-id>10</default-user-id> </result> </get-db> </database> </packet>

Supported Operations

237

Changing Database User Credentials


You can change credentials of certain database user. To change login or password of a database user, specify the user's ID. You can update preferences for multiple users in a single set-db-user packet.

In this section:
Request Packet Structure.................................................................................. 237 Request Samples .............................................................................................. 238 Response Packet Structure ............................................................................... 239 Response Samples ........................................................................................... 240

Request Packet Structure


A request XML packet retrieving users from the database includes the set-db-users operation node:
<packet version="1.4.2.0"> <database> <set-db-user> </set-db-user> </database> </packet>

The set-db-user node is presented by type DatabaseSetDBUserInputType (database_input.xsd), and its graphical representation is as follows:

The id node is required. It specifies ID of the database user whose preferences are to be changed. Data type: integer. The login node is optional. It specifies new login name for the database user. Data type: string. The password node is required. It specifies new password for the database user. Data type: string (length should be more than five digits). The password-type node is optional. Specifies if it is a plain or encrypted password. Data type:string. Allowed values: plain | crypt.

238

Supported Operations

Remarks You can change credentials for multiple database users in a single packet. Add as many set-db-user operations to the packet as the number of different users you want to update.
<packet version="1.4.2.0"> <database> <set-db-user> ... </set-db-user> ... <set-db-user> ... </set-db-user> </database> </packet>

Request Samples
Changing database user credentials This request packet sets new password for the database user identified by ID 61.
<packet version="1.4.2.0"> <database> <set-db-user> <id>61</id> <password>a1b2c3d</password> </set-db-user> </database> </packet>

This request packet sets new password and login name for the database user identified by ID 67.
<packet version="1.4.2.0"> <database> <set-db-user> <id>61</id> <login>MyNewName</login> <password>a1b2c3d</password> </set-db-user> </database> </packet>

Supported Operations

239

Changing credentials of multiple database users This request packet sets new passwords for two database users (identified by ID 6 and ID 7).
<packet version="1.4.2.0"> <database> <set-db-user> <id>6</id> <password>a1b2c3d</password> </set-db-user> <set-db-user> <id>7</id> <password>b1c2d3e</password> </set-db-user> </database> </packet>

Response Packet Structure


The set-db-user node of the output XML packet is presented by type DatabaseSetDBUserOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the set-db-user operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set-db-user operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set-db-user operation fails. Data type: string. The id node is optional. If the set-db-users operation succeeds, it specifies the id of the updated database user. Data type: string.

240

Supported Operations

Response Samples
Changing database user credentials This request packet sets new password for the database user identified by ID 61.
<packet version="1.4.2.0"> <database> <set-db-user> <id>61</id> <password>a1b2c3d</password> </set-db-user> </database> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <database> <set-db-user> <result> <status>ok</status> <id>61</id> </result> </set-db-user> </database> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <database> <set-db-user> <result> <status>error</status> <errcode>1013</errcode> <errtext>Database user does not exist</errtext> </result> </set-db-user> </database> </packet>

Supported Operations

241

Changing credentials for multiple database users This request packet sets new login names and passwords for the database users identified by ID=61 and ID=68.
<packet version="1.4.2.0"> <database> <set-db-user> <id>61</id> <login>testUser</login> <password>a1b2c3d</password> </set-db-user> <set-db-user> <id>68</id> <login>secondUser</login> <password>abc2c3d</password> </set-db-user> </database> </packet>

If the user with ID 61 was not found on server, and the user with ID 68 was successfully updated, the response packet looks as the follows:
<packet version="1.4.2.0"> <database> <set-db-user> <result> <status>ok</status> <id>61</id> </result> </set-db-user> <set-db-user> <result> <status>ok</status> <id>68</id> </result> </set-db-user> </database> </packet>

242

Supported Operations

Retrieving Database Users Info


You can retrieve information on users of the certain database. To retrieve information on database users, specify the ID of the database. You can retrieve information about users of multiple databases in a single get-db-users operation.

In this section:
Request Packet Structure.................................................................................. 242 Request Samples .............................................................................................. 243 Response Packet Structure ............................................................................... 244 Response Samples ........................................................................................... 245

Request Packet Structure


A request XML packet retrieving users info from the database includes the get-db-users operation node:
<packet version="1.4.2.0"> <database> <get-db-users> </get-db-users> </database> </packet>

The get-db-user node is presented by type DatabaseGetDBInputType (database_input.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (see page 204) section. Data type: DatabaseUserFilterType. The db-id node is optional. It specifies the ID of the database from which information about users is retrieved. Data type: integer.

Remarks Note: In API RPC v.1.5.1.0 and later versions, the get-db-user node is presented by type DatabaseGetDBUsersInputType (database_input.xsd).

Supported Operations

243

You can retrieve information from multiple databases using a single get-db-users operation. Add as many db-id parameters to the filtering rule as the number of different databases you want to scan.
<database> <get-db-users> <filter> <db-id>...</db-id> <db-id>...</db-id> </filter> </get-db-users> </database>

Note: Use the <filter/> parameter to retrieve information about all users from all databases available for the user identified by credentials from HTTP header.

Request Samples
Retrieving information about users of database This request packet retrieves information on all users of the database with ID 79.
<packet version="1.4.2.0"> <database> <get-db-users> <filter> <db-id>79</db-id> </filter> </get-db-users> </database> </packet>

Retrieving information about all users of all databases This request packet retrieves information on all users of all available databases.
<packet version="1.4.2.0"> <database> <get-db-users> <filter/> </get-db-users> </database> </packet>

244

Supported Operations

Response Packet Structure


The get-db-users node of the output XML packet is presented by type DatabaseGetDBUsersOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-db-users operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-db--users operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-db--user operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 204) section. The id node is optional. If the get-db-users operation succeeds, it specifies the database user ID. Data type: integer. The login node is optional. If the get-db-users operation succeeds, it specifies login name of the database user. Data type: string. The db-id node is optional. If the get-db-users operation succeeds, it specifies ID of the database where the user is located. Data type: integer.

Supported Operations

245

Response Samples
Retrieving information about users of database This request packet retrieves information about all users of the database with ID=79.
<packet version="1.4.2.0"> <database> <get-db-users> <filter> <db-id>79</db-id> </filter> </get-db-users> </database> </packet>

If two users (UserOne and UserTwo) were found in the database, the response from the server looks as follows:
<packet version="1.4.2.0"> <database> <get-db-users> <result> <status>ok</status> <filter-id>79</filter-id> <id>15</id> <login>UserOne</login> <db-id>79</db-id> </result> <result> <status>ok</status> <filter-id>79</filter-id> <id>15</id> <login>UserTwo</login> <db-id>79</db-id> </result> </get-db-users> </database> </packet>

If the database was not found, the response from the server looks as follows:
<packet version="1.4.2.0"> <database> <get-db-users> <result> <status>ok</status> <errcode>1015<errcode> <errtext>Database does not exist</errtext> <filter-id>79</filter-id> </result> <get-db-users> <database> </packet>

246

Supported Operations

Deleting Database Users


You can remove user accounts from a certain database. Specify the user login name and ID of the database where you want to remove the user. You can remove all users from all databases in a single del-db-user operation.

In this section:
Request Packet Structure.................................................................................. 246 Request Samples .............................................................................................. 247 Response Packet Structure ............................................................................... 248 Response Samples ........................................................................................... 249

Request Packet Structure


A request XML packet deleting a user from the database includes the del-db-user operation node:
<packet version="1.4.2.0"> <database> <del-db-user> </del-db-user> </database> </packet>

The del-db-user node is presented by type DatabaseDelDBUserInputType (database_input.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (see page 204) section. Data type: DatabaseUserFilterType. The id node is optional. It specifies the ID of the user you want to delete. Data type: integer. The db-id node is optional. It specifies the ID of the database where a new user will be created. Data type: integer.

Supported Operations

247

Remarks You can delete multiple users from the database using a single packet. Add as many del-db-user operations as the number of different users you want to delete from the database.
<database> <del-db-user> </del-db-user> ... <del-db-user> </add-db-user> </database>

You can also delete all users from the different databases using this construction. Note: Use the <filter/> parameter if you want to delete all users from all databases available for the sender.

Request Samples
Deleting a database user This packet removes the user with ID 55 from a database.
<packet version="1.4.2.0"> <database> <del-db-user> <filter> <id>55</id> </filter> </del-db-user> </database> </packet>

Deleting multiple database users This packet removes all users from the database with ID 45.
<packet version="1.4.2.0"> <database> <del-db-user> <filter> <db-id>45</db-id> </filter> </del-db-user> </database> </packet>

248

Supported Operations

This packet removes all users from all databases available for the user identified by credentials from HTTP header.
<packet version="1.4.2.0"> <database> <del-db-user> <filter/> </del-db-user> </database> </packet>

Response Packet Structure


The del-db-user node of the output XML packet is presented by type DatabaseDelDBUserOutputType (database_output.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the del-db-user operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the del-db--user operation fails. Data type: integer. The errtext node is optional. It returns the error message if the del-db--user operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 204) section. The id node is required. If the del-db-user operation succeeds, it specifies the database user ID. Data type: integer.

Supported Operations

249

Response Samples
Deleting database user This request packet removes the user with ID 55 from the database with ID 2.
<packet version="1.4.2.0"> <database> <del-db-user> <filter> <id>55</id> </filter> </del-db-user> </database> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <database> <del-db-user> <result> <status>ok</status> <filter-id>55</filter-id> <id>55</id> </result> </del-db-user> </database> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <database> <del-db-user> <result> <status>ok</status> <errcode>1013<errcode> <errtext>User does not exist</errtext> <filter-id>55</filter-id> </result> </del-db-user> </database> </packet>

250

Supported Operations

Deleting multiple database users This request packet removes all users from the database with ID 45.
<packet version="1.4.2.0"> <database> <del-db-user> <db-id>45</db-id> </del-db-user> </database> </packet>

Two users (ID 7 and ID 8) were removed from the database. The response from the server looks as follows:
<packet version="1.4.2.0"> <database> <del-db-user> <result> <status>ok</status> <filter-id>45</filter-id> <id>7</id> </result> <result> <status>ok</status> <filter-id>45</filter-id> <id>8</id> </result> </del-db-user> </database> </packet>

A negative response can look as follows:


<packet version="1.4.2.0"> <database> <del-db-user> <result> <status>ok</status> <errcode>1015<errcode> <errtext>Database does not exist</errtext> <filter-id>45</filter-id> </result> </del-db-user> </database> </packet>

Supported Operations

251

Managing Desktop Presets


Operator: <desktop> XML Schema: desktop.xsd Plesk version: Plesk 7.5.6 Win | Unix 8.0 and later API RPC version: 1.4.0.0 and higher Plesk user: Plesk Administrator Description The desktop operator is used to modify desktop items of Plesk users' home pages by applying different desktop presets. The presets are the files containing configuration of desktop elements. You can have several presets for your interface and switch between them when needed. Desktop presets can be of one of the following types: presets for administrators presets for domain administrators presets for clients presets for resellers

Each of these user types has a default preset that is applied to their home pages by default. Supported operations

SET-ADMIN (see page 252) changes Plesk Administrator preset SET-DEFAULT-PRESET (see page 255) chooses the default preset for Plesk users PRESET-LIST (see page 260) retrieves info on presets specified by ID ADD-PRESET (see page 265) overwrites the file of presets

252

Supported Operations

REMOVE-PRESET (on page 270) removes presets specified by name and type, or ID

In this section:
Changing Plesk Administrator Preset .................................................................252 Choosing Default Preset ....................................................................................255 Retrieving Preset Preferences ...........................................................................260 Adding Preset ....................................................................................................265 Removing Preset ...............................................................................................270

Changing Plesk Administrator Preset


Use the set-admin operation to change the view of the Plesk Administrator desktop. You can specify only presets for administrators.

In this section:
Request Packet Structure.................................................................................. 252 Request Samples .............................................................................................. 253 Response Packet Structure ............................................................................... 253 Response Samples ........................................................................................... 254

Request Packet Structure


A request XML packet changing the Plesk Administrator desktop view includes the setadmin operation node:
<packet version="1.4.2.0"> <desktop> <set-admin> ... </set-admin> </desktop> </packet>

The set-admin node is presented by the SetAdminInputCommandType type (desktop.xsd), and its graphical representation is as follows:

The desktop-preset node is required. It specifies the name of the preset. Data type: string.

Supported Operations

253

Request Samples
This packet applies preset Default Administrator Desktop to the desktop of Plesk Administrator.
<packet version="1.4.2.0"> <desktop> <set-admin> <desktop-preset>Default Administrator Desktop</desktop-preset> </set-admin> </desktop> </packet>

This packet applies preset MyPreset to the desktop of Plesk Administrator.


<packet version="1.4.2.0"> <desktop> <set-admin> <desktop-preset>MyPreset</desktop-preset> </set-admin> </desktop> </packet>

Response Packet Structure


The set-admin node of the output XML packet is presented by type SetAdminResult (desktop.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DesktopOpResultType (desktop.xsd). The status node is required. It specifies the execution status of the set-admin operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set-admin operation fails. Data type: integer.

254

Supported Operations

The errtext node is optional. It returns the error message if the set-admin operation fails. Data type: string. The id node is optional. It holds ID of the preset if the operation succeeds. Data type: integer.

Response Samples
Request sample This request packet applies preset Default Administrator Desktop to the desktop of Plesk Administrator.
<packet version="1.4.2.0"> <desktop> <set-admin> <desktop-preset>Default Administrator Desktop</desktop-preset> </set-admin> </desktop> </packet>

Response sample A positive response from the server can look as follows:
<packet version="1.4.2.0"> <desktop> <set-admin> <result> <status>ok</status> <id>1</id> </result> </set-admin> </desktop> </packet>

If the preset was not found on the server, or the type of preset differs from 'admin', a response from the server can look as follows:
<packet version="1.4.2.0"> <desktop> <set-admin> <result> <status>error</status> <errcode>1013</errcode> <errtext>Preset Default Client Desktop with type admin has not been found in database</errtext> </result> </set-admin> </desktop> </packet>

Supported Operations

255

Choosing Default Preset


Use the set-default-preset operation to choose default preset for Plesk users except for Plesk Administrator. If you choose a default preset for these Plesk users, it will be immediately applied to their home pages. The default preset for administrators will be applied to Plesk Administrator's desktop only if Administrator's current preset was not found on the server.

In this section:
Request Packet Structure.................................................................................. 255 Request Samples .............................................................................................. 256 Response Packet Structure ............................................................................... 257 Response Samples ........................................................................................... 258

Request Packet Structure


A request XML packet changing default preset includes the set-default-preset operation node:
<packet version="1.4.2.0"> <desktop> <set-default-preset> ... </set-default-preset> </desktop> </packet>

The set-default-preset node is presented by the SetDefaultPresetInputCommandType type (desktop.xsd), and its graphical representation is as follows:

The name node is required. It specifies the name of the preset. Data type: string. The id node is required. It specifies the ID of the preset. Data type: integer. The type node is required. It specifies the type of the preset. For information on types of presets, refer to the Managing Desktop Presets (see page 251) section. Data type: string. Allowed values: admin | client | domain | reseller.

256

Supported Operations

Remarks You can choose default preset for multiple types of presets. Add as many set-defaultpreset operations as number of presets you want to set as default. Types of the presets should differ.

Request Samples
Defining default preset for presets of the same type This packet chooses default preset for Plesk clients.
<packet version="1.4.2.0"> <desktop> <set-default-preset> <name>ClientDefaultPreset</name> <type>client</type> </set-default-preset> </desktop> </packet>

Defining default preset for multiple types of presets This packet performs the following operations: Chooses the preset called ClientDefaultPreset as default for desktop of Plesk clients Chooses the preset called DomainDefaultPreset as default for desktop of Plesk domain administrators

<packet version="1.4.2.0"> <desktop> <set-default-preset> <name>ClientDefaultPreset</name> <type>client</type> </set-default-preset> <set-default-preset> <name>DomainDefaultPreset</name> <type>domain</type> </set-default-preset> </desktop> </packet>

Supported Operations

257

Response Packet Structure


The set-default-preset node of the output XML packet is presented by type SetDefaultResult (desktop.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DesktopOpResultType (desktop.xsd). The status node is required. It specifies the execution status of the set-default-preset operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set-default-preset operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set-default-preset operation fails. Data type: string. The id node is optional. It holds ID of the preset if the operation succeeds or if the ID was specified in the request packet. Data type: integer.

258

Supported Operations

Response Samples
Defining default preset for presets of the same type This request packet chooses default preset for Plesk clients.
<packet version="1.4.2.0"> <desktop> <set-default-preset> <name>ClientDefaultPreset</name> <type>client</type> </set-default-preset> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <set-default-preset> <result> <status>ok</status> <id>2</id> </result> </set-default-preset> </desktop> </packet>

If the preset was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <desktop> <set-default-preset> <result> <status>error</status> <errcode>1013</errcode> <errtext>Preset Default Client Desktop with type admin has not been found in database</errtext> </result> </set-default-preset> </desktop> </packet>

Supported Operations

259

Defining default preset for multiple types of presets This request packet performs the following operations: Chooses the preset called ClientDefaultPreset as default for desktop of Plesk clients Chooses the preset called DomainDefaultPreset as default for desktop of Plesk domain owners

<packet version="1.4.2.0"> <desktop> <set-default-preset> <name>ClientDefaultPreset</name> <type>client</type> </set-default-preset> <set-default-preset> <name>DomainDefaultPreset</name> <type>domain</type> </set-default-preset> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <set-default-preset> <result> <status>ok</status> <id>2</id> </result> </set-default-preset> <set-default-preset> <result> <status>ok</status> <id>3</id> </result> </set-default-preset> </desktop> </packet>

260

Supported Operations

Retrieving Preset Preferences


Use the preset-list operation to retrieve preferences of a preset. For info on presets, refer to the Managing Desktop Presets (see page 251) section.

In this section:
Request Packet Structure.................................................................................. 260 Request Samples .............................................................................................. 260 Response Packet Structure ............................................................................... 262 Response Samples ........................................................................................... 263

Request Packet Structure


A request XML packet retrieving preferences of a preset includes the preset-list operation node:
<packet version="1.4.2.0"> <desktop> <preset-list> ... </preset-list> </desktop> </packet>

The preset-list node is presented by the PresetListsInputCommandType type (desktop.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: PresetSimpleFilterType (desktop.xsd). The id node is optional. It specifies the ID of the preset. If ID is not specified, the operation will return all presets available on the server. Data type: integer.

Remarks You can retrieve preferences of multiple presets in a single packet. Add as many id parameters as number of presets info on which you want to retrieve.

Supported Operations

261

Request Samples
Retrieving preferences of a single preset This packet retrieves preferences of the preset specified by ID 5.
<packet version="1.4.2.0"> <desktop> <preset-list> <filter> <id>5</id> </filter> </preset-list> </desktop> </packet>

Retrieving preferences of multiple presets This packet retrieves preferences the presets specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <desktop> <preset-list> <filter> <id>5</id> <id>7</id> </filter> </preset-list> </desktop> </packet>

This packet retrieves preferences of all presets on the server.


<packet version="1.4.2.0"> <desktop> <preset-list> <filter/> </preset-list> </desktop> </packet>

262

Supported Operations

Response Packet Structure


The preset-list node of the output XML packet is presented by type PresetlistsResult (desktop.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DesktopOpAdvancedpresetType (desktop.xsd). The status node is required. It specifies the execution status of the preset-list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the preset-list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the preset-list operation fails. Data type: string. The id node is optional. It holds ID of the preset. Data type: integer. The preset node is optional. It holds preferences of the preset. Data type: PresetType (desktop.xsd). The following nodes are nested in the response packet only if the operation succeeds: The name node is required. It specifies the preset name. Data type: string. The type node is required. It specifies the type of the preset. For info on types of presets, refer to the Managing Desktop Presets (see page 251) section. Data type: string. Allowed values: admin | client | domain.

The default node is optional. It specifies if the preset will be default for the specified type of presets. For information on default presets, refer to the Managing Desktop Presets (see page 251) section. Data type: none.

Supported Operations

263

Response Samples
Retrieving preferences of a single preset This request packet retrieves preferences of the preset specified by ID 5.
<packet version="1.4.2.0"> <desktop> <preset-list> <filter> <id>5</id> </filter> </preset-list> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <preset-list> <result> <status>ok</status> <id>5</id> <preset> <name>ClientDefaultPreset</name> <type>client</type> <default></default> </preset> </result> </preset-list> </desktop> </packet>

If the preset was not found on the server, the result looks as follows:
<packet version="1.4.2.0"> <desktop> <preset-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Preset Default Client Desktop with type admin has not been found in database</errtext> <id>5</id> </result> </preset-list> </desktop> </packet>

264

Supported Operations

Retrieving preferences of multiple presets This request packet retrieves preferences of all presets on the server.
<packet version="1.4.2.0"> <desktop> <preset-list> <filter/> </preset-list> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <preset-list> <result> <status>ok</status> <id>5</id> <preset> <name>ClientDefaultPreset</name> <type>client</type> <default></default> </preset> </result> <result> <status>ok</status> <id>7</id> <preset> <name>MyDefaultPreset</name> <type>admin</type> </preset> </result> </preset-list> </desktop> </packet>

Supported Operations

265

Adding Preset
Use the add-preset operation to add a new preset. For information on presets, refer to the Managing Desktop Presets (see page 251) section.

In this section:
Request Packet Structure.................................................................................. 265 Request Samples .............................................................................................. 265 Response Packet Structure ............................................................................... 267 Response Samples ........................................................................................... 268

Request Packet Structure


A request XML packet adding a preset includes the add-preset operation node:
<packet version="1.4.2.0"> <desktop> <add-preset> ... </add-preset> </desktop> </packet>

The add-preset node is presented by the AddPresetInputCommandType type (desktop.xsd), and its graphical representation is as follows:

The file node is required. It specifies full name of the file containing desktop preset. It should be located on the server. If the preset was uploaded using the upload operator, you can retrieve the file value from the response packet of the operation. For information on the upload operator, refer to the Uploading Files to Server (see page 1368) section. Data type: string. The overwrite node is optional. It specifies if the file will be overwritten in case of name conflict. Data type: none.

Remarks You can add multiple presets in a single packet. Add as many add-preset operations as number of presets to be added.

266

Supported Operations

Request Samples
Adding a preset This packet adds preset MyPreset to desktop presets located on the server. If preset MyPreset already exists on the server, the operation will overwrite the old file.
<packet version="1.4.2.0"> <desktop> <add-preset> <file>/tmp/mypreset.xml</file> <overwrite/> </add-preset> </desktop> </packet>

Adding multiple presets This packet adds the presets MyPreset and DomainPreset to desktop presets located on the server.
<packet version="1.4.2.0"> <desktop> <add-preset> <file>/tmp/mypreset.xml</file> <overwrite/> </add-preset> <add-preset> <file>/tmp/domainpreset.xml</file> <overwrite/> </add-preset> </desktop> </packet>

Supported Operations

267

Response Packet Structure


The add-preset node of the output XML packet is presented by type AddPresetResult (desktop.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DesktopOpResultType (common.xsd). The status node is required. It specifies the execution status of the add-preset operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add-preset operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add-preset operation fails. Data type: string. The id node is optional. It holds ID of the preset if the operation succeeds. Data type: integer.

268

Supported Operations

Response Samples
Adding a preset This request packet adds preset MyPreset to desktop presets located on the server. If preset MyPreset already exists on the server, the operation will overwrite the old file.
<packet version="1.4.2.0"> <desktop> <add-preset> <file>/tmp/mypreset.xml</file> <overwrite/> </add-preset> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <add-preset> <result> <status>ok</status> <id>12</id> </result> </add-preset> </desktop> </packet>

If the file was not a valid preset, the response is as follows:


<packet version="1.4.2.0"> <desktop> <add-preset> <result> <status>error</status> <errcode>1002</errcode> <errtext>Unable to import desktop presets: The uploaded XML file contains a syntax error.</errtext> </result> </add-preset> </desktop> </packet>

Supported Operations

269

Adding multiple presets This packet adds the presets MyPreset and DomainPreset to desktop presets located on the server.
<packet version="1.4.2.0"> <desktop> <add-preset> <file>/tmp/mypreset.xml</file> <overwrite/> </add-preset> <add-preset> <file>/tmp/domainpreset.xml</file> <overwrite/> </add-preset> </desktop> </packet>

A possible response from the server when the second file was not found can look as follows:
<packet version="1.4.2.0"> <desktop> <add-preset> <result> <status>ok</status> <id>12</id> </result> </add-preset> <add-preset> <result> <status>error</status> <errcode>1002</errcode> <errtext>Desktop preset file '' cannot be read</errtext> </result> </add-preset> </desktop> </packet>

270

Supported Operations

Removing Preset
Use the remove-preset operation to remove a preset. For information on presets, refer to the Managing Desktop Presets (see page 251) section. Note: You cannot delete default presets.

In this section:
Request Packet Structure.................................................................................. 270 Request Samples .............................................................................................. 271 Response Packet Structure ............................................................................... 272 Response Samples ........................................................................................... 273

Request Packet Structure


A request XML packet removing a preset includes the remove-preset operation node:
<packet version="1.4.2.0"> <desktop> <remove-preset> ... </remove-preset> </desktop> </packet>

The remove-preset node is presented by the RemovePresetInputCommandType type (desktop.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: PresetfilterType (desktop.xsd). The name node is optional. It specifies the name of the preset. If you specify the preset name, you should also specify the preset type. Data type: string. The type node is optional. It specifies the type of the preset. If you specify the preset type, you should also specify the preset name. Data type: string. The id node is optional. It specifies the ID of the preset. Data type: integer.

Supported Operations

271

Remarks Using different filtering rules, you can do the following operations: Remove a single preset specified by name and type Remove one or more presets specified by ID

The following filtering rule specifies the client preset called ClientPreset.
<filter> <name>ClientPreset</name> <type>client</type> </filter>

The following filtering rule specifies the presets with ID 7 and ID 9


<filter> <id>7</id> <id>9</id> </filter>

Presets can be filtered either by name and type, or by ID. The packet containing type, name, and ID parameters in a single filter node will be considered invalid by Plesk. To use different filtering rules in a single packet, add as many remove-preset operations to the request packet as the number of different filtering rules to be applied.

Request Samples
Removing a preset This packet removes client preset MyPreset.
<packet version="1.4.2.0"> <desktop> <remove-preset> <filter> <name>MyPreset</name> <type>client</type> </filter> </remove-preset> </desktop> </packet>

Removing multiple presets This packet removes the presets specified by ID 6 and ID 8.
<packet version="1.4.2.0"> <desktop> <remove-preset> <filter> <id>6</id> <id>8</id> </filter> </remove-preset> </desktop> </packet>

272

Supported Operations

This packet removes administrator presets MyPreset and MyAdminPreset.


<packet version="1.4.2.0"> <desktop> <remove-preset> <filter> <name>MyPreset</name> <type>admin</type> </filter> </remove-preset> <remove-preset> <filter> <name>MyAdminPreset</name> <type>admin</type> </filter> </remove-preset> </desktop> </packet>

Response Packet Structure


The remove-preset node of the output XML packet is presented by type RemovePresetResult (desktop.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: DesktopOpResultType (common.xsd). The status node is required. It specifies the execution status of the remove-preset operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the remove-preset operation fails. Data type: integer. The errtext node is optional. It returns the error message if the remove-preset operation fails. Data type: string. The id node is optional. It holds ID of the preset if the operation succeeds or if it was specified in the request packet. Data type: integer.

Supported Operations

273

Response Samples
Removing a preset This request packet removes client preset MyPreset.
<packet version="1.4.2.0"> <desktop> <remove-preset> <filter> <name>MyPreset</name> <type>client</type> </filter> </remove-preset> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <remove-preset> <result> <status>ok</status> <id>12</id> </result> </remove-preset> </desktop> </packet>

If the preset was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <desktop> <remove-preset> <result> <status>error</status> <errcode>1013</errcode> <errtext>Desktop preset "MyPreset" of type "client" was not found in repository.</errtext> </result> </remove-preset> </desktop> </packet>

274

Supported Operations

Removing multiple presets This packet removes the presets specified by ID 6 and ID 8.
<packet version="1.4.2.0"> <desktop> <remove-preset> <filter> <id>6</id> <id>8</id> </filter> </remove-preset> </desktop> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <desktop> <remove-preset> <result> <status>ok</status> <id>6</id> </result> <result> <status>ok</status> <id>8</id> </result> </remove-preset> </desktop> </packet>

This packet removes administrator presets MyPreset and MyAdminPreset.


<packet version="1.4.2.0"> <desktop> <remove-preset> <filter> <name>MyPreset</name> <type>admin</type> </filter> </remove-preset> <remove-preset> <filter> <name>MyAdminPreset</name> <type>admin</type> </filter> </remove-preset> </desktop> </packet>

Supported Operations

275

If the presets were not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <desktop> <remove-preset> <result> <status>error</status> <errcode>1013</errcode> <errtext>Desktop preset "MyPreset" of type "admin" was not found in repository.</errtext> </result> </remove-preset> <remove-preset> <result> <status>error</status> <errcode>1013</errcode> <errtext>Desktop preset "MyPreset" of type "admin" was not found in repository.</errtext> </result> </remove-preset> </desktop> </packet>

276

Supported Operations

Managing DNS
Operator: <dns> XML Schema: dns_input.xsd, dns_output.xsd Plesk version: all versions API RPC version: all versions Plesk user: Plesk Administrator Description Plesk supports the following functionality: Managing DNS records (see page 282) Managing ACL (see page 304) Managing SOA record and zone parameters (see page 315) Managing name servers (see page 329) Managing local or remote DNS servers (see page 350) Managing recursive requests to DNS servers (see page 368)

In this section:
Filtering Issues .................................................................................................. 278 Managing DNS Records .................................................................................... 282 Managing ACL .................................................................................................. 304 Managing SOA Records and Zone Parameters................................................. 315 Managing Name Servers ................................................................................... 329 Managing Local or Remote DNS Servers .......................................................... 350 Managing DNS Recursion ................................................................................. 368

Supported Operations

277

Supported operations

ADD_REC (see page 282) adds a DNS record of the specified type to the specified domain zone GET_REC (see page 291) retrieves information about certain DNS records

278

Supported Operations

DEL_REC (see page 297) removes the specified DNS record(s) GET_ACL (see page 304) retrieves access control lists (ACL) from the server ADD_TO_ACL (see page 306) adds hosts to ACL REMOVE_FROM_ACL (see page 310) removes hosts from ACL SET (see page 316) updates the SOA record settings for the specified zone or zone template GET (see page 323) retrieves the SOA record settings SWITCH (see page 330) switches the DNS zone type between master and slave ADD_MASTER_SERVER (see page 334) adds a new master DNS server for the specified zone GET_MASTER_SERVER (see page 340) retrieves the master server for the specified zone DEL_MASTER_SERVER (see page 345) removes the master server for the specified zone ENABLE (see page 350) enables the name server for the specified zone DISABLE (see page 355) disables the name server for the specified domain ENABLE-REMOTE-DNS (see page 359) switches the DNS server to primary mode DISABLE-REMOTE-DNS (see page 362) switches the DNS server to slave mode GET-STATUS-REMOTE-DNS (see page 365) retrieves the status of the remote DNS server SET-RECURSION (see page 368) sets up preferences of recursive requests to DNS server GET-RECURSION (see page 372) retrieves the recursion preferences DNS server GET-SUPPORTED-RECURSION (see page 374) retrieves the available types of recursion for the DNS server

Supported Operations

279

Filtering Issues
Filtering is the way the request XML packet indicates the object to which the operation will be applied. The request XML packet filters data using a special <filter> section. A single filter can specify multiple DNS records, all specified either by ID, domain ID or host IP address. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule. A packet that retrieving information about the master DNS server for domain with ID 3 can look as follows:
<packet version="1.4.2.0"> <dns> <get_master_server> <filter> <domain_id>3</domain_id> </filter> </get_master_server> </dns> </packet>

The filter-id node is nested in a response packet of the get_master_server operation. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet. Domain ID DNS Record ID Domain alias ID

It is done to trace the request parameters in case of error. Data type: anySimpleType. If the filter node is left blank (<filter/>), the filter-id parameter will hold the ID of the object. The blank filter means that all records are matched by this rule. Note: The <filter-id> node appears in API RPC 1.4.2.0. Earlier versions of the protocol do not support this node. There are three kinds of filters, specified by different types: aclFilter (see page 280) simpleFilter (see page 280) dnsSelectionFilter (see page 281)

280

Supported Operations

In this section:
aclFilter ............................................................................................................. 280 simpleFilter ........................................................................................................ 280 dnsSelectionFilter .............................................................................................. 281

aclFilter
The aclFilter filter is used to retrieve and update Access Control Lists (ACL). For more information, refer to the Retrieving ACL (see page 304), Adding to ACL (see page 306), and Removing From ACL (see page 310) sections. This filter is used in the get_acl, add_to_acl, remove_from_acl operations. Data type:aclFilter (dns_input.xsd). The graphical representation of the filter node is as follows:

The host node is required. It specifies the IP address of a host. Data type: string.

You can match multiple hosts using this filter as in the following example:
<filter> <host>192.168.1.1</host> <host>192.168.7.5</host> </filter>

simpleFilter
The simpleFilter filter is used to match one or more domains or domain aliases by ID. This filter is used in get, set, switch, enable, disable operations. Data type: simpleFilterType (dns_input.xsd).The graphical representation of the filter node is as follows:

The domain_id node is required. It specifies the domain ID in Plesk database. Data type: integer. The domain_alias_id is required. It specifies the domain alias ID in Plesk database. For information on domain aliases, refer to the Managing Domain Aliases (see page 487) section. Data type: integer. This filter parameter is supported starting with API RPC v.1.4.0.0.

Supported Operations

281

Remarks You can match multiple domains using this filter. The combination of two filtering rules in one filter node can look as follows:
<filter> <domain_id>1</domain_id> <domain_id>12</domain_id> </filter>

You can also match multiple domain aliases using this filter. The combination of two filtering rules in one filter node can look as follows:
<filter> <domain_alias_id>1</domain_alias_id> <domain_alias_id>12</domain_alias_id> </filter>

Note: You can use either domain_id, or domain_alias_id when using this filter. The packet that contains both domain_id and domain_alias_id parameters in a single filter node will be considered invalid by Plesk server.

dnsSelectionFilter
The dnsSelectionFilter filter match DNS records by ID, domain ID, or domain alias ID. It is used in get_rec, del_rec, del_master_server, get_master_server operations. Data type: dnsSelectionFilterType (dns_input.xsd). The graphical representation of the filter node is as follows:

The domain_id node is optional. It specifies the domain ID in Plesk database. Data type: integer. The id node is optional. It specifies the DNS record ID in Plesk database. Data type: integer. The domain_alias_id node is optional. It specifies the domain alias ID in Plesk database. For information on domain aliases, refer to the Managing Domain Aliases (see page 487) section. Data type: integer. This filter parameter is supported starting with API RPC v.1.4.0.0.

282

Supported Operations

Remarks You can also match multiple domains, domain aliases, DNS records using this filter. The combination of two filtering rules in one filter node can look as follows:
<filter> <id>1</id> <id>2</id> <id>3</id> </filter>

Note: You can use either id, domain_id, or domain_alias_id when using this filter. The packet that contains a combination of id, domain_id, and domain_alias_id parameters in a single filter node will be considered invalid by Plesk server.

Managing DNS Records


In Plesk, DNS resource records include zone template records, and domain or domain alias zone records. Template is a server-level set of rules for zone files of the newly created domains: When a new domain or domain alias is created, Plesk automatically generates zone file for it basing on server templates.

In this section:
Adding DNS Record .......................................................................................... 282 Retrieving DNS Records ................................................................................... 291 Deleting DNS Records ...................................................................................... 297

Adding DNS Record


Resource Records define data types in the Domain Name System (DNS). Resource Records identified by RFC 1035 are stored in binary format internally for use by DNS software. But resource records are sent across a network in text format while they perform zone transfers. The following record types are available in Plesk: A (Address). Used for storing an IP address (specifically, an IPv4 32-bit address) associated with a domain name. NS (Authoritative name server). Specifies a host name (which must have an A record associated with it), where DNS information can be found about the domain name to which the NS record is attached. NS records are the basic infrastructure on which DNS is built; they stitch together distributed zone files into a directed graph that can be efficiently searched. Defined in RFC 1035. CNAME (Canonical name for a DNS alias). Note that if a domain name has a CNAME record associated with it, then it can not have any other record types. In addition, CNAME records should not point to domain names which themselves have associated CNAME records, so CNAME only provides one layer of indirection.

Supported Operations

283

MX (Mail Exchanger). Each MX record specifies a domain name (which must have an A record associated with it) and a priority; a list of mail exchangers is then ordered by priority when delivering mail. MX records provide one level of indirection in mapping the domain part of an email address to a list of host names which are meant to receive mail for that domain name. Critical part of the infrastructure used to support SMTP email. PTR (Domain name pointer). Provides a general indirection facility for DNS records. Most often used to provide a way to associate a domain name with an IPv4 address in the IN-ADDR.ARPA domain. TXT (Text string). Arbitrary binary data, up to 255 bytes in length. AXFR (Asynchronous Full Transfer Zone). SRV (service) records are a generalization and expansion of features provided by MX records. Where MX records work only for mail delivery and provide "failover" via the Priority value, SRV records add in support for load balancing (via the Weight value) and port selection (via the Port value). This type of records is available only in Plesk for Windows via API RPC v.1.5.0.0 and later.

Note: You can add a DNS record for the specified domain or to the DNS zone template. On creation of a new domain, Plesk automatically generates zone file for the domain or domain alias basing on the server template.

In this section:
Request Packet Structure.................................................................................. 284 Request Samples .............................................................................................. 285 Response Packet Structure ............................................................................... 288 Response Samples ........................................................................................... 289

284

Supported Operations

Request Packet Structure


A request XML packet adding a new DNS record to Plesk database includes the add_rec operation node:
<packet version="1.4.2.0"> <dns> <add_rec> </add_rec> </dns> </packet>

The add_rec node is presented by the dnsRecord type (plesk_dns.xsd). Its graphical representation is as follows:

The domain_id node is optional. If specified, the DNS record will be added to DNS records for the domain with the corresponding ID. Data type: integer. The domain_alias_id node is optional. If specified, the DNS record will be added to DNS records for the domain alias with the corresponding ID. The support of this node has started since 1.4.0.0 version of the API RPC protocol. Data type: integer. The type node is required. It specifies the type of the DNS record. For more information about DNS types, refer to the Adding a DNS Record (see page 282) section. Data type: string. Allowed values: A | NS | CNAME | MX | PTR | TXT | SOA | AXFR | SRV

Supported Operations

285

The host node is required. It specifies the IP address or name of a host that will be used by DNS. Data type: string. The value node is required. It specifies the value that will be linked with the host value. Data type: string. The opt node is optional. It holds optional information about the DNS record. Data type: string.

Note: If the domain_id and domain_alias_id parameters are omitted, the DNS record will be added to the DNS zone template. You can add multiple DNS records using a single packet. Add as many <add-rec> operations as the number of DNS records you want to add.
<dns> <add_rec> </add_rec> ... <add_rec> </add_rec> </dns>

Note: In case of SRV record, the host node stands for Target host, the value stands for Service name. The opt node can contain additional XML code in the following format:<Srv Protocol="" Port="" Priority="" Weight=""/>.

Request Samples
Adding a single record to a domain DNS zone This packet adds an NS record which makes ns.example.com. the nameserver for the host example.com. (domain ID of example.com is 1).
<packet version="1.5.1.0"> <dns> <add_rec> <domain_id>1</domain_id> <type>NS</type> <host/> <value>ns.example.com.</value> </add_rec> </dns> </packet>

286

Supported Operations

This packet links domain mail.example.com. (domain ID of example.com is 1) to IP address 192.0.2.12.


<packet version="1.5.1.0"> <dns> <add_rec> <domain_id>1</domain_id> <type>A</type> <host>mail</host> <value>192.0.2.12</value> </add_rec> </dns> </packet>

This packet sets example.com. as the canonical name for domain ftp.example.com. (domain ID of example.com is 1).
<packet version="1.5.1.0"> <dns> <add_rec> <domain_id>1</domain_id> <type>CNAME</type> <host>ftp</host> <value>example.com.</value> </add_rec> </dns> </packet>

This packet adds an MX DNS record which makes mailex.example.net. the main mail server for domain mail-exchange.example.com. (domain ID of example.com. is 1).
<packet version="1.5.1.0"> <dns> <add_rec> <type>MX</type> <host>mail-exchange</host> <value>mailex.example.net</value> <opt>0</opt> </add_rec> </dns> </packet>

Supported Operations

287

This packet adds a PTR DNS record which makes domain community.example.com. the domain name pointer for the subnet 192.0.2.0/24 (domain ID of example.com. is 1).
<packet version="1.5.1.0"> <dns> <add_rec> <type>PTR</type> <host>192.0.2.0</host> <value>community</value> <opt>24</opt> </add_rec> </dns> </packet>

This packet adds a textual description to the domain about.example.com. (domain ID of example.com. is 1).
<packet version="1.5.1.0"> <dns> <add_rec> <type>TXT</type> <host>about</host> <value>The best place to improve your experiences.</value> </add_rec> </dns> </packet>

This packet adds an SRV record for LDAP service on host 192.0.2.4.
<packet version="1.5.1.0"> <dns> <add_rec> <domain_id>11</domain_id> <type>SRV</type> <host>_LDAP._tcp.ldap.domain-test-480908606.tst.</host> <value>192.0.2.4.</value> <opt>5 25 220</opt> </add_rec> </dns> </packet>

Adding a single record to the server DNS zone template This packet adds to the server DNS template an MX record.
<packet version="1.5.1.0"> <dns> <add_rec> <type>MX</type> <host/> <value>mymail.&lt;domain&gt;</value> <opt>25</opt> </add_rec> </dns> </packet>

288

Supported Operations

Adding multiple DNS records This packet adds A and MX DNS records to DNS zone template.
<packet version="1.5.1.0"> <dns> <add_rec> <type>MX</type> <host/> <value>mymail.&lt;domain&gt;</value> <opt>25</opt> </add_rec> <add_rec> <type>A</type> <host>newsome</host> <value>&lt;ip&gt;</value> </add_rec> </dns> </packet>

Response Packet Structure


The add_rec node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add_rec operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the add_rec operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the add_rec operation fails. Data type: string. The id node is optional. It returns the ID of the DNS record; it is required if the add_rec operation has succeeded. Returns the unique identifier of the DNS record just added to Plesk. Data type: integer.

Supported Operations

289

Response Samples
Adding a single DNS record This request packet adds an NS record.
<packet version="1.4.2.0"> <dns> <add_rec> <domain_id>1</domain_id> <type>NS</type> <host>Mydomain.com.</host> <value>ns.Mydomain.com.</value> </add_rec> </dns> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <add_rec> <result> <status>ok</status> <id>17</id> </result></add_rec> </dns> </packet>

If the domain ID was not found on the server, negative response from the server looks as follows:
<packet version="1.4.2.0"> <dns> <add_rec> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> </result> </add_rec> </dns> </packet>

290

Supported Operations

Adding multiple DNS records This request packet adds A DNS record to DNS zone template and MX record to domain with ID 1.
<packet version="1.4.2.0"> <dns> <add_rec> <domain_id>1</domain_id> <type>NS</type> <host>Mydomain.com.</host> <value>ns.Mydomain.com. </value> </add_rec> <add_rec> <type>A</type> <host>mail.&lt;domain&gt;.</host> <value> &lt;ip&gt;</value> </add_rec> </dns> </packet>

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <add_rec> <result> <status>ok</status> <id>10</id> </result> </add_rec> <add_rec> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> </result> </add_rec> </dns> </packet>

Supported Operations

291

Retrieving DNS Records


Both zone template records and domain or domain alias zone records can be retrieved using the get_rec operation. You can retrieve multiple records in a single get_rec operation using filtering rules. For more information about filters, refer to the Filtering Issues (see page 278) section.

In this section:
Request Packet Structure.................................................................................. 291 Request Samples .............................................................................................. 292 Response Packet Structure ............................................................................... 294 Response Samples ........................................................................................... 295

Request Packet Structure


A request XML packet retrieving a DNS record from Plesk database includes the get_rec operation node:
<packet version="1.4.2.0"> <dns> <get_rec> </get_rec> </dns> </packet>

The graphical representation of the get_rec node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 281) section. Data type: dnsSelectionFilterType(dns_input.xsd). The template node is optional. If present, only DNS zone template records are available for retrieving. In this case domain_id or domain_alias_id cannot be specified as a filtering rule. Data type: none.

Note: If you leave the filter node blank (<filter/>), all resource records (zone template records or zone records depending on presence of the template node in the request packet) will be retrieved.

292

Supported Operations

You can retrieve multiple DNS records in a single packet. Add as many get_rec operations as the number of different filtering rules.
<dns> <get_rec> </get_rec> ... <get_rec> </get_rec> </dns>

Request Samples
Retrieving a single DNS record This packet retrieves information on the DNS record with ID 8.
<packet version="1.4.2.0"> <dns> <get_rec> <filter> <id>8</id> </filter> </get_rec> </dns> </packet>

Retrieving multiple DNS records This packet retrieves zone parameters of the domain with ID 15.
<packet version="1.4.2.0"> <dns> <get_rec> <filter> <domain_id>8</domain_id> </filter> </get_rec> </dns> </packet>

This packet retrieves zone parameters of the domain alias with ID 1.


<packet version="1.4.2.0"> <dns> <get_rec> <filter> <domain_alias_id>1</domain_alias_id> </filter> </get_rec> </dns> </packet>

Supported Operations

293

This packet retrieves zone parameters of the domain alias with ID 1 and the domain with ID 7.
<packet version="1.4.2.0"> <dns> <get_rec> <filter> <domain_alias_id>1</domain_alias_id> </filter> </get_rec> <get_rec> <filter> <domain_id>7</domain_id> </filter> </get_rec> </dns> </packet>

This packet retrieves zone parameters all domains and domain aliases on the server.
<packet version="1.4.2.0"> <dns> <get_rec> <filter/> </get_rec> </dns> </packet>

This packet retrieves all DNS zone template records.


<packet version="1.4.2.0"> <dns> <get_rec> <filter/> <templates/> </get_rec> </dns> </packet>

294

Supported Operations

Response Packet Structure


The get_rec node of the output XML packet is structured as follows:

The result node is optional. It is required if the operation get_rec succeeds, and the data set retrieved from the server is not empty. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_rec operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get_rec operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get_rec operation fails. Data type: string. The id node is required if the get_rec operation has succeeded. Returns the unique identifier of the DNS record. Data type: integer. The data node is optional. It is required if the get_rec operation has succeeded. Data type: dnsRecord (dns_input.xsd). The node is structured as follows:

Supported Operations

295

The domain_id node is optional. If specified, the DNS record is retrieved from zone parameters for the domain with the corresponding ID. Data type: integer. The domain_alias_id node is optional. If specified, the DNS record is retrieved from zone parameters for the domain alias with the corresponding ID. The support of this node has started since 1.4.0.0 version of the API RPC protocol. Data type: integer. The type node is optional. It is required if the operation succeeded. It specifies the type of the DNS record. For more information about DNS types, please visit the Adding a DNS Record (see page 282) section. Data type: string. Allowed values: A | NS | CNAME | MX | PTR | TXT | SOA | AXFR | SRV The host node is optional. It is required if the operation succeeded. It specifies the IP address or name of a host, that will be used by DNS. Data type: string. The value node is optional. It is required if the operation succeeded. It specifies the value that will be linked with the host value. Data type: string. The opt node is optional. It holds optional information about the DNS record. Data type: string.

Response Samples
Retrieving a single DNS record This request packet retrieves the DNS record with ID 8.
<packet version="1.4.2.0"> <dns> <get_rec> <filter> <id>8</id> </filter> </get_rec> </dns> </packet>

If the DNS record with ID 8 was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <dns> <get_rec> </get_rec> </dns> </packet>

296

Supported Operations

If the DNS record with ID 8 was found on the server, the response can look as follows:
<packet version="1.4.2.0"> <dns> <get_rec> <result> <status>ok</status> <id>8</id> <data> <domain_id>8</domain_id> <type>NS</type> <host>Mydomain.com.</host> <value>ns.Mydomain.com.</value> <opt></opt> </data> </result> </get_rec> </dns> </packet>

Retrieving multiple DNS records This request packet retrieves zone preferences of the domain with ID 8.
<packet version="1.4.2.0"> <dns> <get_rec> <filter> <domain_id>8</domain_id> </filter> </get_rec> </dns> </packet>

If the domain with ID 8 was not found on the server, the response from the server looks as follows:
<packet version="1.4.2.0"> <dns> <get_rec> </get_rec> </dns> </packet>

Supported Operations

297

If the domain with ID 8 was found on the server, a response from the server can look as follows:
<packet version="1.4.2.0"> <dns> <get_rec> <result> <status>ok</status> <id>18</id> <data> <domain_id>8</domain_id> <type>NS</type> <host>Mydomain.com</host> <value>ns.Mydomain.com. </value> <opt></opt> </data> </result> <get_rec> <result> <status>ok</status> <id>19</id> <data> <domain_id>8</domain_id> <type>PTR</type> <host></host> <value>Mydomain.com</value> <opt></opt> </data> </result> </get_rec> </dns> </packet>

Deleting DNS Records


Both zone template records and domain or domain alias zone records can be deleted using the del_rec operation. You can retrieve multiple records in a single del_rec operation using filtering rules. For more information about filters, refer to the Filtering Issues (see page 278) section.

In this section:
Request Packet Structure.................................................................................. 298 Request Samples .............................................................................................. 299 Response Packet Structure ............................................................................... 301 Response Samples ........................................................................................... 302

298

Supported Operations

Request Packet Structure


A request XML packet deleting a DNS record from Plesk database includes the get_rec operation node:
<packet version="1.4.2.0"> <dns> <del_rec> </del_rec> </dns> </packet>

The graphical representation of the del_rec node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 281) section. Data type: dnsSelectionFilterType(dns_input.xsd). The template node is optional. If present, only DNS zone template records are available for deleting. In this case domain_id or domain_alias_id cannot be specified as a filtering rule. Data type: none.

Note: If you leave the filter node blank (<filter/>) all records (zone template records or zone records, depending on presence of the template node in the request packet) will be removed. You can delete multiple DNS records in a single packet. Add as many del_rec operations as the number of different filtering rules.
<dns> <del_rec> </del_rec> ... <del_rec> </del_rec> </dns>

Supported Operations

299

Request Samples
Deleting a single DNS record This request packet deletes DNS record with ID 75
<packet version="1.4.2.0"> <dns> <del_rec> <filter> <id>75</id> </filter> </del_rec> </dns> </packet>

Deleting multiple DNS records This request packet deletes DNS records from the zone of domain with ID 7.
<packet version="1.4.2.0"> <dns> <del_rec> <filter> <domain_id>7</domain_id> </filter> </del_rec> </dns> </packet>

This request packet deletes DNS records from zones of the domains with ID 7 and 8.
<packet version="1.4.2.0"> <dns> <del_rec> <filter> <domain_id>7</domain_id> <domain_id>8</domain_id> </filter> </del_rec> </dns> </packet>

300

Supported Operations

This request packet deletes DNS records from the zone of the domain with ID 7, and the record with ID 5.
<packet version="1.4.2.0"> <dns> <del_rec> <filter> <domain_id>7</domain_id> </filter> </del_rec> <del_rec> <filter> <id>5</id> </filter> </del_rec> </dns> </packet>

This request packet deletes DNS records from zone files of all domain aliases and domains.
<packet version="1.4.2.0"> <dns> <del_rec> <filter/> </del_rec> </dns> </packet>

This request packet deletes all DNS records from the server template.
<packet version="1.4.2.0"> <dns> <del_rec> <filter/> <template/> </del_rec> </dns> </packet>

Supported Operations

301

Response Packet Structure


The del_rec node of the output XML packet is structured as follows:

The result node is optional. It is required if the operation del_rec succeeds and the data set retrieved from the server is not empty. If the id was set as a filtering rule in the request packet, the result node is also required. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the del_rec operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the del_rec operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the del_rec operation fails. Data type: string. The id node is required if the del_rec operation has succeeded. If the id was set as a filtering rule in the request packet, the id node is also required. Returns the unique identifier of the DNS record. Data type: integer.

302

Supported Operations

Response Samples
Deleting a single DNS record This request packet deletes DNS record with ID 75.
<packet version="1.4.2.0"> <dns> <del_rec> <filter> <id>75</id> </filter> </del_rec> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <del_rec> <result> <status>ok</status> <id>75</id> </result> </del_rec> </dns> </packet>

If the DNS record with ID 75 was not found on the server, the response from the server looks as follows:
<packet version="1.4.2.0"> <dns> <del_rec> <result> <status>error</status> <errcode>1013</errcode> <errtext>DNS record does not exist.</errtext> <id>75</id> </result> </del_rec> </dns> </packet>

Supported Operations

303

Deleting multiple DNS records This request packet deletes DNS records for the domain ID 7 and the record with ID 5.
<packet version="1.4.2.0"> <dns> <del_rec> <filter> <domain_id>7</domain_id> </filter> </del_rec> <del_rec> <filter> <id>5</id> </filter> </del_rec> </dns> </packet>

Three DNS records for the domain alias were deleted. The record with ID 5 was not found on the server. A response packet can look as follows:
<packet version="1.4.2.0"> <dns> <del_rec> <result> <status>ok</status> <id>17</id> </result> <result> <status>ok</status> <id>18</id> </result> <result> <status>ok</status> <id>19</id> </result> </del_rec> <del_rec/> </dns> </packet>

304

Supported Operations

Managing ACL
The Access Control List (ACL) is a concept in computer security used to enforce privilege separation. You can define the hosts which can perform operations on your name server.

In this section:
Retrieving ACL .................................................................................................. 304 Adding Hosts to ACL ......................................................................................... 306 Removing Host From ACL................................................................................. 310

Retrieving ACL
To retrieve the ACL of your name server, use the get_acl operation. The get_acl operation in a request packet has the following graphics presentation:

Data type: none. Request packet sample


<packet version="1.4.2.0"> <dns> <get_acl/> </dns> </packet>

In this section:
Response Packet Structure ............................................................................... 305 Response Samples ........................................................................................... 306

Supported Operations

305

Response Packet Structure


The get_acl operation in a response packet has the following graphics presentation:

The result node is optional. It is required in case when the get_acl operation has succeeded, or when an error (if it occurred) was not of a system type. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_acl operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get_acl operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get_acl operation fails. Data type: string. The host node is optional. It is required if the del_acl operation has succeeded. Returns the IP address or name of hosts from ACL. Data type: string.

306

Supported Operations

Response Samples
A response packet can look as follows:
<packet version="1.4.2.0"> <dns> <get_acl> <result> <status>ok</status> <host>127.0.0.1</host> </result> <result> <status>ok</status> <host>127.0.0.2</host> </result> </get_acl> </dns> </packet>

If the ACL list is empty, the response packet looks as follows:


<packet version="1.4.2.0"> <dns> <get_acl> <result> <status>ok</status> </result> </get_acl> </dns> </packet>

Adding Hosts to ACL


To add a new host to the ACL of your name server, use the add_to_acl operation. You can add multiple hosts to ACL using a single packet.

In this section:
Request Packet Structure.................................................................................. 307 Request Samples .............................................................................................. 307 Response Packet Structure ............................................................................... 308 Response Samples ........................................................................................... 309

Supported Operations

307

Request Packet Structure


A request XML packet adding a new host to the ACL includes the add_to_acl operation node:
<packet version="1.4.2.0"> <dns> <add_to_acl> </add_to_acl> </dns> </packet>

The graphical representation of the add_to_acl node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 280) section. Data type: aclFilter (dns_input.xsd).

You can add multiple hosts to the ACL in a single packet using filters. Add as many host parameters to the filter node as the number of hosts you want to add to the ACL.

Request Samples
This packet adds host 192.168.34.56 to the ACL.
<packet version="1.4.2.0"> <dns> <add_to_acl> <filter> <host>192.168.34.56</host> </filter> </add_to_acl> </dns> </packet>

This packet adds hosts 192.168.34.56 and 12.16.34.56 to the ACL.


<packet version="1.4.2.0"> <dns> <add_to_acl> <filter> <host>192.168.34.56</host> <host>12.16.34.56</host> </filter> </add_to_acl> </dns> </packet>

308

Supported Operations

Response Packet Structure


The add_to_acl node of the output XML packet is structured as follows:

The result node is optional. It is required in case when an error (if it occurred) was not of a system type. Data type: aclresultType (common.xsd). The status node is required. It specifies the execution status of the get_acl operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get_acl operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get_acl operation fails. Data type: string. The host node is optional. It is required in case when an error (if it occurred) was not of a common type. Returns the IP address or name of hosts from the ACL. Data type: string.

Supported Operations

309

Response Samples
Adding a single host to ACL This request packet adds host 192.168.34.56 to the ACL.
<packet version="1.4.2.0"> <dns> <add_to_acl> <filter> <host>192.168.34.56</host> </filter> </add_to_acl> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <add_to_acl> <result> <status>ok</status> <host>192.168.34.56</host> </result> </add_to_acl> </dns> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <add_to_acl> <result> <status>error</status> <errcode>1007</errcode> <errtext>IP address 127.0.0.1 already exists.</errtext> </result> </add_to_acl> </dns> </packet>

310

Supported Operations

Adding a single host to ACL This request packet adds host 192.168.34.56 to the ACL two times.
<packet version="1.4.2.0"> <dns> <add_to_acl> <filter> <host>192.168.34.56</host> </filter> </add_to_acl> <add_to_acl> <filter> <host>192.168.34.56</host> </filter> </add_to_acl> </dns> </packet>

A response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <add_to_acl> <result> <status>ok</status> <host>192.168.34.56</host> </result> </add_to_acl> <add_to_acl> <result> <status>error</status> <errcode>1007</errcode> <errtext>IP address 192.168.34.56 already exists.</errtext> </result> </add_to_acl> </dns> </packet>

Supported Operations

311

Removing Host From ACL


To remove a host from the ACL of your name server, use the remove_from_acl operation. You can remove multiple hosts from the ACL using a single packet.

In this section:
Request Packet Structure.................................................................................. 311 Request Samples .............................................................................................. 311 Response Packet Structure ............................................................................... 312 Response Samples ........................................................................................... 313

Request Packet Structure


A request XML packet removing a host from the ACL includes the remove_from_acl operation node:
<packet version="1.4.2.0"> <dns> <remove_from_acl> </remove_from_acl> </dns> </packet>

The graphical representation of the remove_from_acl node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 280) section. Data type: aclFilter (dns_input.xsd).

You can remove multiple hosts from the ACL in a single packet using filters. Add as many host parameters to the filter node as the number of hosts you want to remove from ACL.

Request Samples
This packet removes host 192.168.34.56 from the ACL.
<packet version="1.4.2.0"> <dns> <remove_from_acl> <filter> <host>192.168.34.56</host> </filter> </remove_from_acl> </dns> </packet>

312

Supported Operations

This packet removes hosts 192.168.34.56 and 12.16.34.56 from the ACL.
<packet version="1.4.2.0"> <dns> <remove_from_acl> <filter> <host>192.168.34.56</host> <host>12.16.34.56</host> </filter> </remove_from_acl> </dns> </packet>

Response Packet Structure


The remove_from_acl node of the output XML packet is structured as follows:

The result node is optional. It is required in case when an error (if it occurred) was not of a common type. For more information about common errors, refer to the Common Errors (see page 1383) section. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the remove_from_acl operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the remove_from_acl operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the remove_from_acl operation fails. Data type: string. The host node is optional. It is required in case an error (if it was) was not of a common type. Returns the IP address or name of hosts from the ACL. Data type: string.

Supported Operations

313

Response Samples
Removing a single host to ACL This request packet removes host 192.168.34.56 from the ACL.
<packet version="1.4.2.0"> <dns> <remove_from_acl> <filter> <host>192.168.34.56</host> </filter> </remove_from_acl> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <remove_from_acl> <result> <status>ok</status> <host>192.168.34.56</host> </result> </remove_from_acl> </dns> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <remove_from_acl> <result> <status>error</status> <errcode>1007</errcode> <errtext>IP address 192.168.34.56 does not exists.</errtext> </result> </remove_from_acl> </dns> </packet>

314

Supported Operations

Removing a single host to ACL This request packet adds host 192.168.34.56 to the ACL two times.
<packet version="1.4.2.0"> <dns> <remove_from_acl> <filter> <host>192.168.34.56</host> </filter> </remove_from_acl> <remove_from_acl> <filter> <host>192.168.34.56</host> </filter> </remove_from_acl> </dns> </packet>

A response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <remove_from_acl> <result> <status>ok</status> <host>192.168.34.56</host> </result> </remove_from_acl> <remove_from_acl> <result> <status>error</status> <errcode>1007</errcode> <errtext>IP address 192.168.34.56 already exists.</errtext> </result> </remove_from_acl> </dns> </packet>

Supported Operations

315

Managing SOA Records and Zone Parameters


The first resource record in any Domain Name System (DNS) Zone file should be a Start of Authority (SOA) resource record. The SOA resource record indicates that this DNS name server is the best source of information for the data within this DNS domain. The zone status is the status of DNS service for the specified zone. If you do not specify the zone, the status of the local DNS server is returned.

In this section:
SOA Parameters ............................................................................................... 315 Updating SOA Record ....................................................................................... 316 Retrieving Parameters of SOA Record and Zone .............................................. 323

SOA Parameters
The soa node is presented by type SOAType (plesk_dns.xsd). This type has the following graphics representation:

The ttl node is optional. This is the amount of time (in seconds) that slave DNS servers should store the record in a cache. Plesk sets the default value of one day. Data type: unsignedInt. The refresh node is optional. This is how often (in seconds) the slave name servers check with the primary name server to see if any changes have been made to the domain's zone file. Plesk sets the default value of three hours. RFC 1912 recommends to vary this parameter from 1200 to 43200. Use the 1200 value if your data is volatile and 43200 if not. Data type: integer. Data type: unsignedInt. The retry node is optional. This is the time (in seconds) a slave (secondary) DNS server waits before retrying a failed zone transfer. This time is typically less than the refresh interval. Typical values vary from 180 (three minutes) to 900(15 minutes). Plesk sets the default value of one hour. Data type: unsignedInt.

316

Supported Operations

The expire node is optional. Signed 32-bit value in seconds. Indicates when the zone data is no longer authoritative. Applies to Slaves or Secondary servers only. BIND9 slaves stop responding to queries for the zone when this time has expired and no contact has been made with the master. Thus when the ref values expires the slave will attempt to read the SOA record for the zone - and request a zone transfer AXFR/ IXFR if the sn has changed. If contact is made the expiry and refresh values are reset and the cycle starts again. If the slave fails to contact the master, it will retry every retry period but continue to supply authoritative data for the zone until the expiry value is reached, at which point it will stop answering queries for the domain. RFC 1912 recommends 1209600 to 2419200 seconds (2-4 weeks) to allow for major outages of the master. Plesk sets the default value of one week. Data type: unsignedInt. The minimum node is optional. This is the time (in seconds) during which a secondary server should cache a negative response. The maximum value allowed by BIND 9 for this parameter is 3 hours (10800 seconds). Plesk sets the default value of three hours. Data type: unsignedInt.

Updating SOA Record


Use the set operation to update a SOA record for the DNS zone template, or for the domain (domain alias) specified by ID. The parameters in the SOA record of the zone template will be applied to a new domain or domain alias on creation. You can update multiple SOA records in a single packet. For more information about SOA records, refer to the SOA parameters (see page 315) section. Note: The set operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 317 Request Samples .............................................................................................. 318 Response Packet Structure ............................................................................... 319 Response Samples ........................................................................................... 321

Supported Operations

317

Request Packet Structure


A request XML packet updating a SOA record includes the set operation node:
<packet version="1.4.2.0"> <dns> <set> </set> </dns> </packet>

The graphical representation of the set node is as follows:

The filter node is optional. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 280) section. Data type: simpleFilterType (dns_input.xsd). The soa node is required. Specifies the SOA parameters. Data type: SOAType (plesk_dns.xsd).

Note: If you omit the filter node, the operation will update SOA parameters for the DNS zone template. You can update multiple SOA records in a single packet. Add as many set operations as the number of different filtering rules.
<dns> <set> </set> ... <set> </set> </dns>

318

Supported Operations

Request Samples
Updating a single SOA record This packet updates a SOA record of the domain with ID 12.
<packet version="1.4.2.0"> <dns> <set> <filter> <domain_id>12</domain_id> </filter> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> </set> </dns> </packet>

This packet updates a SOA record of the DNS zone template.


<packet version="1.4.2.0"> <dns> <set> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> </set> </dns> </packet>

Supported Operations

319

Updating multiple SOA records This packet updates SOA records of the domains with ID 12 and 13.
<packet version="1.4.2.0"> <dns> <set> <filter> <domain_id>12</domain_id> <domain_id>13</domain_id> </filter> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> </set> </dns> </packet>

This packet updates SOA records of the domains with ID 5 and ID 7 and the server template SOA record.
<packet version="1.4.2.0"> <dns> <set> <filter> <domain_id>5</domain_id> </filter> <soa> <ttl>8640</ttl> <refresh>1080</refresh> <retry>3600</retry> <expire>60480</expire> <minimum>1080</minimum> </soa> </set> <set> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> </set> </dns> </packet>

320

Supported Operations

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is optional. It is required in case when an error (if it occurred) was not of a system type. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the set operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the set operation fails. Data type: string. The domain_id node is optional. It is required if the domain ID was set as a filtering rule in the request packet. Data type: integer. The domain_alias_id node is optional. It is required if the domain alias ID was set as a filtering rule in the request packet. Data type: integer.

Supported Operations

321

Response Samples
Updating a single SOA record This request packet updates a SOA record of the domain with ID 12.
<packet version="1.4.2.0"> <dns> <set> <filter> <domain_id>12</domain_id> </filter> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> </set> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <set> <result> <status>ok</status> <domain_id>12</domain_id> </result> </set> </dns> </packet>

If the domain with ID 12 was not found on the server, the negative response looks as follows:
<packet version="1.4.2.0"> <dns> <set> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <domain_id>12</domain_id> </result> </set> </dns> </packet>

322

Supported Operations

Updating multiple SOA records This request packet updates SOA records of the domains with ID 12 and ID 13.
<packet version="1.4.2.0"> <dns> <set> <filter> <domain_id>12</domain_id> <domain_id>13</domain_id> </filter> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> </set> </dns> </packet>

If the domain with ID 13 was not found on the server, and the domain with ID 12 was updated, the response packet looks as follows:
<packet version="1.4.2.0"> <dns> <set> <result> <status>ok</status> <domain_id>12</domain_id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain alias does not exist.</errtext> <domain_id>13</domain_id> </result> </set> </dns> </packet>

Supported Operations

323

Retrieving Parameters of SOA Record and Zone


Use the get operation to perform the following: retrieve SOA record, zone type, zone status of the zone specified by domain or domain alias ID retrieve SOA record, zone status of the server template

Local DNS server can be enabled (see page 350) or disabled (see page 355) for the specified zone. When it is enabled, it can act as a "primary" or "slave" name server. If you want to change the type of zone, please refer to the Switching Name Server Mode (see page 330) section. Note: The support of the get operation is started since 1.4.0.0 version of API RPC protocol.

In this section:
Request Packet Structure.................................................................................. 323 Request Samples .............................................................................................. 324 Response Packet Structure ............................................................................... 326 Response Samples ........................................................................................... 327

Request Packet Structure


A request XML packet retrieving a SOA record includes the get operation node:
<packet version="1.4.2.0"> <dns> <get> </get> </dns> </packet>

The graphical representation of the get node is as follows:

The filter node is optional. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 280) section. Data type: simpleFilterType (dns_input.xsd). The soa node is required. If specified, the SOA parameters will be returned in the response packet. Data type: none.

324

Supported Operations

The following table shows the response parameters, if either filter or soa node is omitted.
SOA present Filter present SOA record, zone type, zone status of a domain or alias Filter omitted zone status, SOA record of the server template SOA omitted zone type, zone status of a domain or domain alias

You can retrieve the parameters of multiple domains or domain aliases in a single packet. Add as many get operations as the number of different filtering rules.
<dns> <get> </get> ... <get> </get> </dns>

Request Samples
This packet retrieves a zone type and zone status of the domain with ID 1.
<packet version="1.4.2.0"> <dns> <get> <filter> <domain_id>1</domain_id> </filter> </get> </dns> </packet>

This packet retrieves the SOA record, zone type, and zone status of the domain with ID 1.
<packet version="1.4.2.0"> <dns> <get> <filter> <domain_id>1</domain_id> </filter> <soa/> </get> </dns> </packet>

Supported Operations

325

This packet retrieves the SOA record of the server template and the status of the DNS server.
<packet version="1.4.2.0"> <dns> <get> <soa/> </get> </dns> </packet>

This packet retrieves the following parameters: the SOA record of the server template the status of the DNS server a zone type of the domain with ID 1 a zone status of the domain with ID 1

<packet version="1.4.2.0"> <dns> <get> <soa/> </get> <get> <filter> <domain_id>1</domain_id> </filter> </get> </dns> </packet>

326

Supported Operations

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the set operation fails. Data type: string. The domain_id node is optional. It is required if the domain ID was set as a filtering rule in the request packet. Data type: integer. The domain_alias_id node is optional. It is required if the domain alias ID was set as a filtering rule in the request packet. Data type: integer. The soa node is optional. It is required if the soa node was specified in the request packet. Data type: SOAType (plesk_dns.xsd). The zone_type is optional. It is required if the filter node was specified in the request packet. Specifies the type of the DNS name server. Data type: string. Allowed values: master | slave. The zone_status is optional. It is required if the get operation succeeds. Specifies the status of the local DNS name server. Data type: string. Allowed values: enabled | disabled.

Supported Operations

327

Response Samples
This request packet retrieves the zone type and zone status of the domain with ID 1.
<packet version="1.4.2.0"> <dns> <get> <filter> <domain_id>1</domain_id> </filter> </get> </dns> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <get> <result> <status>ok</status> <domain_id>1</domain_id> <zone_type>master</zone_type> <zone_status>enabled</zone_status> </result> </get> </dns> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <get> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <domain_id>1</domain_id> </result> </get> </dns>

This request packet retrieves the SOA record, zone type, and zone status of the domain with ID 1.
<packet version="1.4.2.0"> <dns> <get> <filter> <domain_id>1</domain_id> </filter> <soa/> </get></dns></packet>

328

Supported Operations

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <get> <result> <status>ok</status> <domain_id>1</domain_id> <soa> <ttl>86400</ttl> <refresh>10800</refresh> <retry>3600</retry> <expire>604800</expire> <minimum>10800</minimum> </soa> <zone_type>master</zone_type> <zone_status>enabled</zone_status> </result> </get> </dns> </packet>

This request packet retrieves a zone type, and zone status of the domain with ID 2 and domain alias with ID 1.

<packet version="1.4.2.0"> <dns> <get> <filter> <domain_alias_id>1</domain_alias_id> </filter> </get> <get> <filter> <domain_id>2</domain_id> </filter> </get> </dns> </packet>

Supported Operations

329

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <get> <result> <status>ok</status> <domain__alias_id>1</domain_alias_id> <zone_type>master</zone_type> <zone_status>enabled</zone_status> </result> </get> <get> <result> <status>ok</status> <domain_id>2</domain_id> <zone_type>master</zone_type> <zone_status>enabled</zone_status> </result> </get> </dns> </packet>

Managing Name Servers


Name servers are defined by domain or domain alias ID. They can be primary or secondary for the zone they manage. Secondary name servers are used when you turn the primary name server to slave mode.

In this section:
Switching Name Server Mode ........................................................................... 330 Adding Primary Name Server ............................................................................ 334 Retrieving Primary Name Servers ..................................................................... 340 Deleting Primary Name Servers ........................................................................ 345

330

Supported Operations

Switching Name Server Mode


To switch a name server between master and slave mode, use the switch operation. You can switch multiple name servers in a single packet. To retrieve the zone type, refer to the Retrieving Parameters of SOA Record and Zone (see page 323) section. Note: The switch operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 330 Request Samples .............................................................................................. 331 Response Packet Structure ............................................................................... 332 Response Samples ........................................................................................... 333

Request Packet Structure


A request XML packet changing name server mode includes the switch operation node:
<packet version="1.4.2.0"> <dns> <switch> </switch> </dns> </packet>

The graphical representation of the switch node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 280) section. Data type: simpleFilterType (dns_input.xsd). The zone_type node is required. Specifies the zone parameters. Data type: string. Allowed values: master | slave.

Supported Operations

331

You can change mode of multiple name servers in a single packet. Add as many switch operations as the number of different filtering rules, you use to change the mode of name servers you need.
<dns> <switch> </switch> ... <switch> </switch> </dns>

Request Samples
Changing status of a single name server This packet makes the name server for the zone specified by domain ID 1 act as a secondary.
<packet version="1.4.2.0"> <dns> <switch> <filter> <domain_id>1</domain_id> </filter> <zone_type>slave</zone_type> </switch> </dns> </packet>

Changing status of multiple name servers This packet makes the name server for the zones specified by domains ID 1 and ID 2 act as a secondary.
<packet version="1.4.2.0"> <dns> <switch> <filter> <domain_id>1</domain_id> <domain_id>2</domain_id> </filter> <zone_type>slave</zone_type> </switch> </dns> </packet>

332

Supported Operations

This packet performs the following: makes the name server for the zone specified by domain ID 1 act as a primary name server makes the name server for the zone specified by domain ID 2 act as secondary name server

<packet version="1.4.2.0"> <dns> <switch> <filter> <domain_id>1</domain_id> </filter> <zone_type>master</zone_type> </switch> <switch> <filter> <domain_id>2</domain_id> </filter> <zone_type>slave</zone_type> </switch> </dns> </packet>

Response Packet Structure


The switch node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the switch operation fails. Data type: unsignedInt The errtext node is optional. It is used to return the error message if the switch operation fails. Data type: string.

Supported Operations

333

The domain_id node is optional. It is required if the domain ID was set as a filtering rule in the request packet. Data type: integer. The domain_alias_id node is optional. It is required if the domain alias ID was set as a filtering rule in the request packet. Data type: integer.

Response Samples
Changing status of a single name server This request packet makes the DNS server act as a secondary for the zone specified by domain ID 1.
<packet version="1.4.2.0"> <dns> <switch> <filter> <domain_id>1</domain_id> </filter> <zone_type>slave</zone_type> </switch> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <switch> <result> <status>ok</status> <domain_id>1</domain_id> </result> </switch> </dns> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <switch> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <domain_id>1</domain_id> </result> </switch> </dns> </packet>

334

Supported Operations

Changing status of multiple name servers This packet makes the DNS server act as a secondary for the zones specified by domains ID 1 and ID 2.
<packet version="1.4.2.0"> <dns> <switch> <filter> <domain_id>1</domain_id> <domain_id>2</domain_id> </filter> <zone_type>slave</zone_type> </switch> </dns> </packet>

A response packet from the server can look as follows:


<packet version="1.4.2.0"> <dns> <switch> <result> <status>ok</status> <domain_id>1</domain_id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <domain_id>2</domain_id> </result> </switch> </dns> </packet>

Supported Operations

335

Adding Primary Name Server


Use the add_master_server operation to add a primary name server. This server will be primary for the zone specified by the domain ID or domain alias ID. You can add multiple primary servers in a single packet. Note: The add_master_server operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 335 Request Samples .............................................................................................. 336 Response Packet Structure ............................................................................... 337 Response Samples ........................................................................................... 338

Request Packet Structure


A request XML packet adding a primary name server includes the add_master_server operation node:
<packet version="1.4.2.0"> <dns> <add_master_server> </add_master_server> </dns> </packet>

The graphical representation of the add_master_server node is as follows:

The domain_id node is required. Specifies the ID of the domain, which zone will be served by the primary name server. Data type: integer. The domain_alias_id node is required. Specifies the ID of the domain alias, which zone will be served by the primary name server. Data type: integer. The ip_address node is required. Specifies the IP address of a primary name server. Data type: integer.

336

Supported Operations

You can add multiple primary name servers in a single packet. Add as many add_master_server operations as the number of different servers you want to add.
<dns> <add_master_server> </add_master_server> ... <add_master_server> </add_master_server> </dns>

Request Samples
Adding a single primary name server This packet adds a primary name server to the zone of the domain with ID 5.
<packet version="1.4.2.0"> <dns> <add_master_server> <domain_id>5</domain_id> <ip_address>10.6.45.18</ip_address> </add_master_server> </dns> </packet>

Adding multiple primary name servers This packet adds a primary name server to the zone of the domain with ID 5 and ID 7.
<packet version="1.4.2.0"> <dns> <add_master_server> <domain_id>5</domain_id> <ip_address>10.6.45.18</ip_address> </add_master_server> <add_master_server> <domain_id>7</domain_id> <ip_address>10.6.45.18</ip_address> </add_master_server> </dns> </packet>

Supported Operations

337

Response Packet Structure


The add_master_server node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add_master_server operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the add_master_server operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the add_master_server operation fails. Data type: string. The id node is optional. It is required if the operation add_master_server has succeeded. Returns the ID of the primary name server in Plesk database. Data type: integer.

338

Supported Operations

Response Samples
Adding a single primary name server This request packet adds a primary name server to the zone of the domain with ID 5.
<packet version="1.4.2.0"> <dns> <add_master_server> <domain_id>5</domain_id> <ip_address>10.6.45.18</ip_address> </add_master_server> </dns> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <add_master_server> <result> <status>ok</status> <id>4</id> </result> </add_master_server> </dns> </packet>

If the IP address parameter has invalid format, the response looks as follows:
<packet version="1.4.2.0"> <dns> <add_master_server> <result> <status>error</status> <errcode>1014</errcode> <errtext>Parser error: Cannot parse the XML from the source specified</errtext> <id>4</id> </result> </add_master_server> </dns> </packet>

Supported Operations

339

If the domain specified by the ID was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <dns> <add_master_server> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist.</errtext> <id>4</id> </result> </add_master_server> </dns> </packet>

Adding multiple primary name servers This request packet adds a primary name server to the zone of the domain with ID 5 and ID 7.
<packet version="1.4.2.0"> <dns> <add_master_server> <domain_id>5</domain_id> <ip_address>10.6.45.18</ip_address> </add_master_server> <add_master_server> <domain_id>7</domain_id> <ip_address>10.6.45.18</ip_address> </add_master_server> </dns> </packet>

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <add_master_server> <result> <status>ok</status> <id>4</id> </result> </add_master_server> <add_master_server> <result> <status>ok</status> <id>5</id> </result> </add_master_server> </dns> </packet>

340

Supported Operations

Retrieving Primary Name Servers


Use the get_master_server operation to retrieve IP addresses of the primary name servers for the specified zone. You can retrieve multiple primary servers in a single packet. Note: The get_master_server operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 340 Request Samples .............................................................................................. 341 Response Packet Structure ............................................................................... 342 Response Samples ........................................................................................... 343

Request Packet Structure


A request XML packet retrieving a primary name server includes the get_master_server operation node:
<packet version="1.4.2.0"> <dns> <get_master_server> </get_master_server> </dns> </packet>

The graphical representation of the get_master_server node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 281) section. Data type: dnsSelectionFilterType (dns_input.xsd).

Note: If the filter node is left blank (<filter/>), the operation will retrieve all primary name servers available for a packet sender on the server. You can retrieve multiple primary name servers in a single packet. Add as many get_master_server operations as the number of different filtering rules you use.
<dns> <get_master_server> </get_master_server> ... <get_master_server> </get_master_server></dns>

Supported Operations

341

Request Samples
Retrieving a single name server This packet retrieves the IP address of the primary name server with ID 5.
<packet version="1.4.2.0"> <dns> <get_master_server> <filter><id>5</id></filter> </get_master_server> </dns> </packet>

Retrieving multiple name servers This packet retrieves primary name servers for the zones specified by domain ID 5 and ID 6.
<packet version="1.4.2.0"> <dns> <get_master_server> <filter> <domain_id>5</domain_id> <domain_id>5</domain_id> </filter> </get_master_server> </dns> </packet>

This packet retrieves primary name servers for the zones specified by domain ID 5 and domain alias ID 6..
<packet version="1.4.2.0"> <dns> <get_master_server> <filter> <domain_id>5</domain_id> </filter> </get_master_server> <get_master_server> <filter> <domain_alias_id>6</domain_alias_id> </filter> </get_master_server> </dns> </packet>

342

Supported Operations

This packet retrieves all primary name servers on the server available for a packet sender.
<packet version="1.4.2.0"> <dns> <get_master_server> <filter/> </get_master_server> </dns> </packet>

Response Packet Structure


The get_master_server node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get_master_server operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get_master_server operation fails. Data type: unsignedInt The errtext node is optional. It is used to return the error message if the get_master_server operation fails. Data type: string. The id node is optional. It is required if the operation get_master_server has succeeded. Returns the ID of the primary name server in Plesk database. Data type: integer.

Supported Operations

343

The filter-id node is optional. It holds the filtering rule parameter. For info on filters, refer to the Filtering Issues (see page 278) section. Data type: integer. The domain_id node is required. Specifies the ID of the domain, which zone will be served by the primary name server. Data type: integer. The domain_alias_id node is required. Specifies the ID of the domain alias, which zone will be served by the primary name server. Data type: integer. The ip_address node is required. Specifies the IP address of a primary name server. Data type: integer.

Response Samples
Retrieving a single name server This packet retrieves the IP address of the primary name server with ID 5.
<packet version="1.4.2.0"> <dns> <get_master_server> <filter><id>5</id></filter> </get_master_server> </dns> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <get_master_server> <result> <status>ok</status> <filter-id>5</filter-id> <id>5</id> <domain_id>1</domain_id> <ip_address>115.16.17.18</ip_address> </result> </get_master_server> </dns> </packet>

If the name server specified by the ID was not found, the response can look as follows:
<packet version="1.4.2.0"> <dns> <get_master_server> <result> <status>error</status> <errcode>1013</errcode> <errtext>Master server is not found. ID : 5</errtext> </result> </get_master_server> </dns> </packet>

344

Supported Operations

If the domain specified by the ID was not found, the response can look as follows:
<packet version="1.4.2.0"> <dns> <get_master_server> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist.</errtext> </result> </get_master_server> </dns> </packet>

Retrieving multiple name servers This packet retrieves primary name servers for the zones specified by domain ID 5 and ID 6, and domain alias ID 16.
<packet version="1.4.2.0"> <dns> <get_master_server> <filter> <domain_id>5</domain_id> <domain_id>6</domain_id> </filter> </get_master_server> <get_master_server> <filter> <domain_alias_id>16</domain_alias_id> </filter> </get_master_server> </dns> </packet>

Two primary servers on domain with ID 5, one on the domain with ID 6 are found. The domain alias with ID 16 was not found on the server. A possible response from the server can look as follows:
<packet version="1.4.2.0"> <dns> <get_master_server> <result> <status>ok</status> <filter-id>5</filter-id> <id>15</id> <domain_id>5</domain_id> <ip_address>15.16.17.18</ip_address> </result> <result> <status>ok</status> <filter-id>5</filter-id> <id>16</id> <domain_id>5</domain_id> <ip_address>11.16.17.18</ip_address> </result> <result>

Supported Operations <status>ok</status> <filter-id>6</filter-id> <id>28</id> <domain_id>6</domain_id> <ip_address>10.6.17.18</ip_address> </result> </get_master_server> <get_master_server> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain alias does not exist.</errtext> </result> </get_master_server> </dns> </packet>

345

Deleting Primary Name Servers


Use the del_master_server operation to delete primary name servers from the specified zone. You can delete multiple primary servers in a single packet. Note: The del_master_server operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 345 Request Samples .............................................................................................. 346 Response Packet Structure ............................................................................... 347 Response Samples ........................................................................................... 348

Request Packet Structure


A request XML packet deleting a primary name server includes the del_master_server operation node:
<packet version="1.4.2.0"> <dns> <del_master_server> </del_master_server> </dns> </packet>

346

Supported Operations

The graphical representation of the del_master_server node is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 281) section. Data type: dnsSelectionFilterType (dns_input.xsd).

Note: If the filter node is left blank (<filter/>), the operation removes all primary name servers available for a packet sender on the server. You can delete multiple primary name servers in a single packet. Add as many del_master_server operations as the number of different filtering rules you use.
<dns> <del_master_server> </del_master_server> ... <del_master_server> </del_master_server> </dns>

Request Samples
Deleting a single name server This packet removes the primary name server specified by ID 5.
<packet version="1.4.2.0"> <dns> <del_master_server> <filter><id>5</id></filter> </del_master_server> </dns> </packet>

Deleting multiple name servers This packet removes primary name servers for the zones specified by domain ID 5 and ID 6.
<packet version="1.4.2.0"> <dns> <del_master_server> <filter> <domain_id>5</domain_id> <domain_id>5</domain_id> </filter> </del_master_server> </dns> </packet>

Supported Operations

347

This packet removes all primary name servers available for a packet sender from Plesk database.
<packet version="1.4.2.0"> <dns> <del_master_server> <filter/> </del_master_server> </dns> </packet>

Response Packet Structure


The get_master_server node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the del_master_server operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the del_master_server operation fails. Data type: unsignedInt The errtext node is optional. It is used to return the error message if the del_master_server operation fails. Data type: string. The id node is optional. It is required if the operation del_master_server has succeeded. Returns the ID of the primary name server in Plesk database. Data type: integer.

348

Supported Operations

Response Samples
Removing a single name server This packet removes the primary name server specified by ID 5.
<packet version="1.4.2.0"> <dns> <del_master_server> <filter><id>5</id></filter> </del_master_server> </dns> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <del_master_server> <result> <status>ok</status> <id>5</id> </result> </del_master_server> </dns> </packet>

If the name server specified by the ID was not found, the response can look as follows:
<packet version="1.4.2.0"> <dns> <del_master_server> <result> <status>error</status> <errcode>1013</errcode> <errtext>Master server is not found. ID : 5</errtext> </result> </del_master_server> </dns> </packet>

If the domain specified by the ID was not found, the response can look as follows:
<packet version="1.4.2.0"> <dns> <del_master_server> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist.</errtext> </result> </del_master_server> </dns> </packet>

Supported Operations

349

Removing multiple name servers This packet deletes primary name servers for the zones specified by domain ID 5 and ID 6, and primary server with ID 25.
<packet version="1.4.2.0"> <dns> <del_master_server> <filter> <domain_id>5</domain_id> <domain_id>6</domain_id> </filter> </del_master_server> <del_master_server> <filter> <id>25</id> </filter> </del_master_server> </dns> </packet>

Three primary servers on the domains with ID 5 and ID 6 were removed. The primary server with ID 25 was not found on the server. A possible response from the server can look as follows:
<packet version="1.4.2.0"> <dns> <del_master_server> <result> <status>ok</status> <id>15</id> </result> <result> <status>ok</status> <id>16</id> </result> <result> <status>ok</status> <id>28</id> </result> </del_master_server> <del_master_server> <result> <status>error</status> <errcode>1015</errcode> <errtext>Master server is not found. ID : 25</errtext> </result> </del_master_server> </dns> </packet>

350

Supported Operations

Managing Local or Remote DNS Servers


All zones on the server can be served by local or remote DNS servers. When the local DNS server is disabled, the zone is served by a remote DNS server.

In this section:
Enabling Local DNS .......................................................................................... 350 Disabling Local DNS ......................................................................................... 355 Enabling Remote DNS Support ......................................................................... 359 Disabling Remote DNS Support ........................................................................ 362 Retrieving Remote DNS Status ......................................................................... 365

Enabling Local DNS


The enable operation is used to enable local DNS support for the current zone. With the operation, you can also enable or disable the local DNS support for the DNS zone template. All the domains or domain alias zones, which were added according to the template with the enabled status, will be supported by local DNS. You can enable the local DNS support for multiple zones in a single packet. To learn how to retrieve the status information for the local DNS server, refer to the Managing SOA Records and Zone Parameters (see page 323) section. Note: The enable operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 351 Request Samples .............................................................................................. 352 Response Packet Structure ............................................................................... 353 Response Samples ........................................................................................... 354

Supported Operations

351

Request Packet Structure


A request XML packet switching on the local DNS support includes the enable operation node:
<packet version="1.4.2.0"> <dns> <enable> </enable> </dns> </packet>

The graphical representation of the enable node is as follows:

The filter node is optional. It specifies the filtering rule. If the filter node is omitted, the DNS zone template will change status to "enable". For more information, refer to the Filtering Issues (see page 281) section. Data type: dnsSelectionFilterType (dns_input.xsd).

You can enable the local DNS support for multiple zones. Add as many enable operations as the number of different filtering rules.
<dns> <enable> </enable> ... <enable> </enable> </dns>

352

Supported Operations

Request Samples
This packet enables the local DNS for the zones specified by domain ID 8 and ID 9.
<packet version="1.4.2.0"> <dns> <enable> <filter> <domain_id>8</domain_id> <domain_id>9</domain_id> </filter> </enable> </dns> </packet>

This packet enables the local DNS for the zones specified by domain ID 8.
<packet version="1.4.2.0"> <dns> <enable> <filter> <domain_id>8</domain_id> </filter> </enable> </dns> </packet>

This packet enables the local DNS for the DNS zone template .
<packet version="1.4.2.0"> <dns> <enable/> </dns> </packet>

Supported Operations

353

Response Packet Structure


The enable node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultOpType (dns_output.xsd). The status node is required. It specifies the execution status of the enable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the enable operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the enable operation fails. Data type: string. The domain_id node is optional. It is required if the domain ID was set as a filtering rule in the response packet. Specifies the ID of the domain, which zone will use local DNS. Data type: integer. The domain_alias_id node is optional. It is required if the domain ID was set as a filtering rule in the response packet. Specifies the ID of the domain alias, which zone will use local DNS. Data type: integer.

354

Supported Operations

Response Samples
This request packet enables the local DNS for the zones specified by domain ID 8 and ID 9.
<packet version="1.4.2.0"> <dns> <enable> <filter> <domain_id>8</domain_id> <domain_id>9</domain_id> </filter> </enable> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <enable> <result> <status>ok</status> <domain_id>8</domain_id> </result> <result> <status>ok</status> <domain_id>9</domain_id> </result> </enable> </dns> </packet>

If the second zone was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <dns> <enable> <result> <status>ok</status> <domain_id>8</domain_id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist.</errtext> </result> </enable> </dns> </packet>

Supported Operations

355

Disabling Local DNS


The disable operation is used to disable the local DNS support for the current zone. With the operation, you can also disable the local DNS support for the DNS zone template. All the domains or domain alias zones, which were added according to the template with the disabled status, will not be supported by local DNS. You can enable the local DNS support for multiple zones in a single packet. To learn how to retrieve the status information for the local DNS server, refer to the Managing SOA Records and Zone Parameters (see page 323) section. Note: The disable operation is supported starting with API RPC protocol v.1.4.0.0.

In this section:
Request Packet Structure.................................................................................. 355 Request Samples .............................................................................................. 356 Response Packet Structure ............................................................................... 357 Response Samples ........................................................................................... 358

Request Packet Structure


A request XML packet switching off the local DNS support includes the disable operation node:
<packet version="1.4.2.0"> <dns> <disable> </disable> </dns> </packet>

The graphical representation of the disable node is as follows:

The filter node is optional. It specifies the filtering rule. If the filter node is omitted, the DNS zone template will changes status to "disable". For more information, refer to the Filtering Issues (see page 281) section. Data type: dnsSelectionFilterType (dns_input.xsd).

356

Supported Operations

You can disable the local DNS support for multiple zones. Add as many disable operations as the number of different filtering rules.
<dns> <disable> </disable> ... <disable> </disable> </dns>

Request Samples
This packet disables the local DNS for the zones specified by domain ID 8 and ID 9.
<packet version="1.4.2.0"> <dns> <disable> <filter> <domain_id>8</domain_id> <domain_id>9</domain_id> </filter> </disable> </dns> </packet>

This packet disables the local DNS for the DNS zone template .
<packet version="1.4.2.0"> <dns> <disable/> </dns> </packet>

Supported Operations

357

Response Packet Structure

The disable node of the output XML packet is structured as follows:

The result node is required. It wraps the response from the server. Data type: resultOpType (dns_output.xsd). The status node is required. It specifies the execution status of the disable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the disable operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the disable operation fails. Data type: string. The domain_id node is optional. It is required if the domain ID was set as a filtering rule in the response packet. Specifies the ID of the domain, which zone will use local DNS. Data type: integer. The domain_alias_id node is optional. It is required if the domain ID was set as a filtering rule in the response packet. Specifies the ID of the domain alias, which zone will use local DNS. Data type: integer.

358

Supported Operations

Response Samples
This request packet disables the local DNS for the zones specified by domain ID 8 and ID 9.
<packet version="1.4.2.0"> <dns> <disable> <filter> <domain_id>8</domain_id> <domain_id>9</domain_id> </filter> </disable> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <disable> <result> <status>ok</status> <domain_id>8</domain_id> </result> <result> <status>ok</status> <domain_id>9</domain_id> </result> </disable> </dns> </packet>

If the second zone was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <dns> <disable> <result> <status>ok</status> <domain_id>8</domain_id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist.</errtext> </result> </disable> </dns> </packet>

Supported Operations

359

Enabling Remote DNS Support


The enable-remote-dns operation is used to disable the local DNS server, and you can use remote DNS servers. This node is available only in Plesk for Windows 8.1 and next versions. Note: The enable-remote-dns operation is supported starting with API RPC protocol v.1.4.2.0. A request XML packet, that enables use of remote DNS servers, includes the enableremote-dns operation node:
<packet version="1.4.2.0"> <dns> <enable-remote-dns/> </dns> </packet>

The graphical representation of the enable-remote-dns node is as follows:

Request packet sample This request packet enables use of remote DNS servers.
<packet version="1.4.2.0"> <dns> <enable-remote-dns/> </dns> </packet>

In this section:
Response Packet Structure ............................................................................... 360 Response Samples ........................................................................................... 361

360

Supported Operations

Response Packet Structure

The enable-remote-dns node is presented by type DNSEnableRemoteDNS (dns_output.xsd) and is structured as follows:

The result node is required. It wraps the information got from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the enable-remote-dns operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the enableremote-dns operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the enableremote-dns operation fails. Data type: string.

Supported Operations

361

Response Samples
This request packet enables use of remote DNS servers.
<packet version="1.4.2.0"> <dns> <enable-remote-dns/> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <enable-remote-dns> <result> <status>ok</status> </result> </enable-remote-dns> </dns> </packet>

If the packet is sent to Plesk for Unix server, the response is as follows:
<packet version="1.4.2.0"> <dns> <enable-remote-dns> <result> <status>error</status> <errcode>1014</errcode> <errtext>Parser error: Request is invalid</errtext> </result> </enable-remote-dns> </dns> </packet>

362

Supported Operations

Disabling Remote DNS Support


The disable-remote-dns operation is used to disable remote DNS servers, and you can use the local DNS server. This node is available only in Plesk for Windows 8.1 and next versions. Note: The disable-remote-dns operation is supported starting with API RPC protocol v.1.4.2.0. A request XML packet, that disables use of remote DNS servers, includes the disableremote-dns operation node:
<packet version="1.4.2.0"> <dns> <disable-remote-dns/> </dns> </packet>

The graphical representation of the disable-remote-dns node is as follows:

Request packet sample This request packet disables use of remote DNS servers.
<packet version="1.4.2.0"> <dns> <disable-remote-dns/> </dns> </packet>

In this section:
Response Packet Structure ............................................................................... 363 Response Samples ........................................................................................... 364

Supported Operations

363

Response Packet Structure


The disable-remote-dns node is presented by type DNSEnableRemoteDNS (dns_output.xsd) and is structured as follows:

The result node is required. It wraps the information got from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the enable-remote-dns operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the enableremote-dns operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the enableremote-dns operation fails. Data type: string.

364

Supported Operations

Response Samples
This request packet disables use of remote DNS servers.
<packet version="1.4.2.0"> <dns> <disable-remote-dns/> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <disable-remote-dns> <result> <status>ok</status> </result> </disable-remote-dns> </dns> </packet>

If the packet is sent to Plesk for Unix server, the response is as follows:
<packet version="1.4.2.0"> <dns> <disable-remote-dns> <result> <status>error</status> <errcode>1014</errcode> <errtext>Parser error: Request is invalid</errtext> </result> </disable-remote-dns> </dns> </packet>

Supported Operations

365

Retrieving Remote DNS Status


Remote DNS servers are enabled or disabled. If remote DNS servers are disabled, all zones are served by the local DNS server. Use the get-status-remote-dns to retrieve the status of remote DNS servers. This node is available only in Plesk for Windows 8.1 and next versions. Note: The get-status-remote-dns operation is supported starting with API RPC protocol v.1.4.2.0. A request XML packet, that retrieves the status of remote DNS servers, includes the get-status-remote-dns operation node:
<packet version="1.4.2.0"> <dns> <get-status-remote-dns/> </dns> </packet>

The graphical representation of the get-status-remote-dns node is as follows:

Request packet sample This request packet retrieves the status of remote DNS servers.
<packet version="1.4.2.0"> <dns> <get-status-remote-dns/> </dns> </packet>

In this section:
Response Packet Structure ............................................................................... 366 Response Samples ........................................................................................... 367

366

Supported Operations

Response Packet Structure


The get-status-remote-dns node is presented by type DNSEnableRemoteDNS (dns_output.xsd) and is structured as follows:

The result node is required. It wraps the information got from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get-status-remotedns operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get-statusremote-dns operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get-statusremote-dns operation fails. Data type: string. The dns-status node is optional. It is required if the operation get-status-remote-dns succeeds. Data type: boolean.

Supported Operations

367

Response Samples
This request packet retrieves the status of remote DNS servers.
<packet version="1.4.2.0"> <dns> <get-status-remote-dns> </dns> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <dns> <get-status-remote-dns <result> <status>ok</status> <dns_status>true</dns_status&gt; </result> </get-status-remote-dns> </dns> </packet>

If the packet is sent to Plesk for Unix server, the response is as follows:
<packet version="1.4.2.0"> <dns> <disable-remote-dns> <result> <status>error</status> <errcode>1014</errcode> <errtext>Parser error: Request is invalid</errtext> </result> </disable-remote-dns> </dns> </packet>

368

Supported Operations

Managing DNS Recursion


When a DNS server receives a recursive request from a client that it is willing to perform recursion for, it will go through the process of resolving the requested domain name by first asking the root servers, which respond with a referral to the top level DNS servers, then asking one of those servers, which respond with a referral to the next level DNS servers, etc. When a DNS server receives a non-recursive request or a request from a client that it is not willing to perform recursion for, it typically responds immediately with whatever local data it has available at the time without doing any additional processing. Four types of recursive requests to the local DNS sever in Plesk are available: off. The recursion is not allowed. on. The recursion is allowed for all requests. localhost. The recursion is allowed for requests from local machine. localnets. The recursion is allowed for requests from local net.

Note: Not all of the following types can be supported by the server. Before setting the recursion type, use the get-supported-recursion to make sure it is supported by the server.

In this section:
Setting Recursion Type ..................................................................................... 368 Retrieving Recursion Type ................................................................................ 372 Retrieving Supported Recursion Types ............................................................. 374

Setting Recursion Type


The type of recursion can be changed by the set-recursion operation. Before setting the recursion type, make sure it is supported by the server. Note: The set-recursion operation is supported starting with API RPC protocol v.1.4.2.0.

In this section:
Request Packet Structure.................................................................................. 369 Request Samples .............................................................................................. 369 Response Packet Structure ............................................................................... 370 Response Samples ........................................................................................... 371

Supported Operations

369

Request Packet Structure


A request XML packet changing the recursion type includes the set-recursion operation node:
<packet version="1.4.2.0"> <dns> <set-recursion> </set-recursion> </dns> </packet>

The set-recursion node is presented by type DNSSetRecursionInputType (dns_input.xsd) and structured as follows:

The value node is required. Specifies the type of recursion. Data type: DNSRecursionValueType (plesk_dns.xsd). Allowed values: on | off | local | localnets.

Request Samples
This packet allows all recursive requests to the local DNS server.
<packet version="1.4.2.0"> <dns> <set-recursion> <value>on</value> </set-recursion> </dns> </packet>

This packet allows recursive requests coming from the local net to the local DNS server.
<packet version="1.4.2.0"> <dns> <set-recursion> <value>localnets</value> </set-recursion> </dns> </packet>

370

Supported Operations

Response Packet Structure


The set-recursion node is presented by type DNSSetRecursionOutputType (dns_output.xsd) and is structured as follows:

The result node is required. It wraps the information got from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the set-recursion operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the setrecursion operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the set-recursion operation fails. Data type: string.

Supported Operations

371

Response Samples
This request packet allows all recursive requests to the local DNS server.
<packet version="1.4.2.0"> <dns> <set-recursion> <value>on</value> </set-recursion> </dns> </packet>

If the recursion type is supported by the server, the response is as follows:


<packet version="1.4.2.0"> <dns> <set-recursion> <result> <status>ok</status> </result> </set-recursion> </dns> </packet>

If the recursion type is not supported by the server, the response is as follows:
<packet version="1.4.2.0"> <dns> <set-recursion> <result> <status>error</status> <errcode>4605</errcode> <errtext>Not supported type for DNS recursion</errtext> </result> </set-recursion> </dns> </packet>

372

Supported Operations

Retrieving Recursion Type


A request XML packet, that retrieves a type of recursion, includes the get-recursion operation node:
<packet version="1.4.2.0"> <dns> <get-recursion/> </dns> </packet>

The graphical representation of the get-recursion node is as follows:

Note: The get-recursion operation is supported starting with API RPC protocol v.1.4.2.0. Request packet sample This request packet retrieves the recursion type.
<packet version="1.4.2.0"> <dns> <get-recursion/> </dns> </packet>

In this section:
Response Packet Structure ............................................................................... 373 Response Samples ........................................................................................... 374

Supported Operations

373

Response Packet Structure

The get-recursion node is presented by type DNSGetRecursionOutputType (dns_output.xsd) and is structured as follows:

The result node is required. It wraps the information got from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get-recursion operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the getrecursion operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get-recursion operation fails. Data type: string. The value node is optional. It is used to return a type of recursion if the get-recursion operation succeeds. Data type: string.

374

Supported Operations

Response Samples
This request packet retrieves the recursion type.
<packet version="1.4.2.0"> <dns> <get-recursion/> </dns> </packet>

A response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <get-recursion> <result> <status>ok</status> <value>on</value> </result> </get-recursion> </dns> </packet>

Retrieving Supported Recursion Types


The get-supported-recursion operation retrieves the types of recursive requests, supported by the local DNS server. For more information on types of requests, please refer to the Managing DNS recursion (see page 368) section. A request XML packet, that retrieves the supported types of recursion, includes the getsupported-recursion operation node:
<packet version="1.4.2.0"> <dns> <get-supported-recursion/> </dns> </packet>

The graphical representation of the get-supported-recursion node is as follows:

Note: The set-recursion operation is supported starting with API RPC protocol v.1.4.2.0.

Supported Operations

375

Request packet sample This request packet retrieves the types of recursive requests supported by the server.
<packet version="1.4.2.0"> <dns> <get-supported-recursion/> </dns> </packet>

In this section:
Response Packet Structure ............................................................................... 375 Response Samples ........................................................................................... 376

Response Packet Structure


The get-supported-recursion node is presented by type DNSGetSupportedRecursionOutputType (dns_output.xsd) and is structured as follows:

The result node is required. It wraps the information got from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get-supportedrecursion operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the getsupported-recursion operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the getsupported-recursion operation fails. Data type: string. The value node is optional. It is used to return the supported types of recursion if the get-supported-recursion operation succeeds. Data type: string.

376

Supported Operations

Response Samples
This request packet retrieves the types of recursive requests supported by the server.
<packet version="1.4.2.0"> <dns> <get-supported-recursion/> </dns> </packet>

A response from the server can look as follows:


<packet version="1.4.2.0"> <dns> <get-supported-recursion> <result> <status>ok</status> <value>on</value> <value>localnets</value> <value>local</value> </result> </get-supported-recursion> </dns> </packet>

Supported Operations

377

Managing Domain Accounts


Operator: <domain> XML Schema: domain_input.xsd, domain_output.xsd, plesk_domain.xsd Plesk version: all versions API RPC version: all versions Plesk user: Plesk Administrator, Plesk reseller (since protocol version 1.6.0.0), Plesk client Description Adding a new domain in Plesk is equivalent to creating a domain account. A domain account holds the information about the domain administrator and various domain settings (hosting settings, limits on use of Plesk resources, performance settings, etc.). Domain accounts can be created by Plesk users who are allowed to manage domains (Plesk Administrator, Plesk resellers, or Plesk clients). All these users can create domains for themselves, and, besides, Plesk Administrator can create domains for any Plesk client or reseller. Plesk resellers can create domains for their Plesk clients and transfer domain accounts from one of their Plesk clients to another, if the corresponding reseller permission is set. Managing domain accounts includes creating, deleting, settings various domain/ Domain Administrator settings. Settings Domain accounts are used to store a collection of domain settings. These settings specify various resources at the domains disposal, and the capabilities of Domain Administrator as well. These settings are as follows: General account information Domain Administrator settings Domain Administrator permissions Hosting settings Limits on use of Plesk resources Disk usage settings Domain statistics settings Domain preferences Performance settings

For details, refer to the Domain Settings (on page 383) section.

378

Supported Operations

Supported operations

ADD (see page 422) creates a domain account and sets general information, hosting settings, limits, preferences, and domain administrator settings GET (see page 429) retrieves information on domains from Plesk database SET (see page 444) updates domain settings in Plesk database DEL (see page 440) removes domains from Plesk database CFORM_BUTTONS_LIST (see page 452) retrieves list of buttons displayed on the home page of a domain administrator GET_TRAFFIC (see page 459) retrieves information on traffic spent by the domain(s) between two dates SET_TRAFFIC (see page 468) sets information on traffic spent by the specified domain(s) GET-LIMIT-DESCRIPTOR (on page 472) retrieves descriptor of limits (supported since protocol version 1.5.0.0) GET-PERMISSION-DESCRIPTOR (on page 478) retrieves descriptor of permissions (supported since protocol version 1.5.0.0) GET-PHYSICAL-HOSTING-DESCRIPTOR (on page 482) retrieves descriptor of hosting settings (supported since protocol version 1.5.0.0)

Supported Operations

379

In this section:
Filtering Issues .................................................................................................. 379 Domain Settings ................................................................................................ 383 Creating Domain Account.................................................................................. 422 Getting Information About Domain Accounts ..................................................... 429 Deleting Domain Accounts ................................................................................ 440 Setting Domain Parameters .............................................................................. 444 Getting the Domain Buttons List ........................................................................ 452 Getting Traffic Usage Information ...................................................................... 459 Setting Domain Traffic Settings ......................................................................... 468 Retrieving Descriptor of Limits ........................................................................... 472 Retrieving Descriptor of Permissions ................................................................. 478 Retrieving Descriptor of Hosting Settings .......................................................... 482

Filtering Issues
Filtering is the way a request XML packet indicates the object (one or several domains) to which an operation is to be applied. Parameters nested in the filter node are called filtering rule. The filter node is presented by the DomainFilterType complex type (domain_input.xsd). Its graphical representation is as follows:

380

Supported Operations

The id node is optional. It specifies the domain ID. Data type: integer. The client_id node is optional. It is not supported since protocol version 1.6.0.0. Use owner-id node instead. The owner-id node is optional. It specifies the ID of a Plesk user that owns domains. Data type: integer. Supported since protocol version 1.6.0.0. The domain_name node is optional. It is not supported since protocol version 1.6.0.0. Use domain-name node instead. The domain-name node is optional. It specifies the domain name. Data type: string. It is supported since protocol version 1.6.0.0. The client_login node is optional. It is not supported since protocol version 1.6.0.0. Use owner-login node instead. The owner-login node is optional. It specifies the login name of Plesk user who owns domains. Data type: string. It is supported since protocol version 1.6.0.0. The guid node is optional. It specifies the GUID of a domain account. This node is supported since protocol version 1.6.0.0. For details on GUIDs, refer to the API RPC Protocol > GUIDs Overview section of Plesk API RPC Developer's Guide. Data type: string.

Two types of filtering are available: Individual filtering Nodes id and domain-name serve to filter one to many domains individually. Individual filtering is allowed for Plesk Administrator, Plesk resellers and for Plesk clients. Group filtering Nodes owner-id and owner-login serve to filter all domains of certain Plesk users at once. This kind of filtering is allowed for Plesk Administrator and Plesk resellers. Individual filtering The following packet requests hosting settings of domains specified by their id:
<packet version=1.6.0.0> <domain> <get> <filter> <id>124</id> <id>127</id> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

Supported Operations

381

The following packet is identical except it specifies domains by their names:


<packet version=1.6.0.0> <domain> <get> <filter> <domain-name>example.com</domain-name> <domain-name>sample.com</domain-name> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

The following packet is invalid as both the id node and the domain-name node are used in the same filter:
<packet version=1.6.0.0> <domain> <get> <filter> <domain-name>example.com</domain-name> <id>126</id> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

To fix this issue, use two different <get> sections:


<packet version=1.6.0.0> <domain> <get> <filter> <domain-name>example.com</domain-name> </filter> <dataset> <hosting/> </dataset> </get> <get> <filter> <id>126</id> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

382

Supported Operations

Group filtering The following packet removes all domains owned by two Plesk users:
<packet version=1.6.0.0> <domain> <del> <filter> <owner-id>1324</owner-id> <owner-id>1325</owner-id> </filter> </del> </domain> </packet>

The same packet removes domains of JDoe and RRoe Plesk users:
<packet version=1.6.0.0> <domain> <del> <filter> <owner-login>JDoe</owner-login> <owner-loginn>RRoe</owner-login> </filter> </del> </domain> </packet>

The following packet is invalid as it uses both the owner-id node and the owner-login node within one filter:
<packet version=1.6.0.0> <domain> <del> <filter> <owner-id>1324</owner-id> <owner-login>RRoe</owner-login> </filter> </del> </domain> </packet>

To fix this packet, use two different <del> sections:


<packet version=1.6.0.0> <domain> <del> <filter> <owner-id>1324</owner-id> </filter> </del> <del> <filter> <owner-login>RRoe</owner-login> </filter> </del></domain></packet>

Supported Operations

383

The following packet sent by Plesk Administrator removes all domains available in Plesk. If sent by a Plesk client/reseller, it will delete all domains of this client/reseller:

<packet version=1.6.0.0> <domain> <del> <filter/> </del> </domain> </packet>

Domain Settings
This section describes a collection of domain and Domain Administrator settings. These settings can be defined when creating a domain or later, and retrieved from Plesk database as well.

In this section:
General Domain Account Information ................................................................ 383 Domain Administrator Settings .......................................................................... 391 Limits, Permissions and Hosting Settings .......................................................... 397 Disk Space Usage Settings ............................................................................... 415 Statistics Settings .............................................................................................. 418 Domain Preferences.......................................................................................... 420 Performance Settings ........................................................................................ 421

384

Supported Operations

General Domain Account Information


General domain information can be added, updated, or retrieved. General domain information is always set when creating a domain account (the add operation). This is done using the gen_setup node (no data type, defined within the add operation node). See the structure of this node in the Node gen_setup (see page 385) section. General information about the specified domains can be retrieved from Plesk database (the get operation). It is returned in the gen_info node of type domainGenInfoType (plesk_domain.xsd). See the structure of this node in the Node gen_info (see page 387) section. General domain information can be updated/modified (the set operation). This is done using the gen_setup node of type SetGenSetupType (plesk_domain.xsd). See the structure of this node in the Node gen_setup (type SetGenSetupType) (see page 390) section.

In this section:
Node gen_setup ................................................................................................ 385 Node gen_info (type domainGenInfoType) ........................................................ 387 Node gen_setup (type setGenSetupType) ........................................................ 390

Supported Operations

385

Node gen_setup
This node is used in the add request packets to set general properties for the newly created domain account. This node does not have its own type, it is defined within the parent node and has the following structure:

The name node is required. It specifies the domain name. Data type: string. The client_id node is optional. It specifies the owner of the new domain account (Plesk client) when the domain is created by Plesk Administrator. If the domain account is created by Plesk client, the node should not be specified. Data type: integer. Is not supported since protocol version 1.6.0.0. Use owner-id, owner-login, or owner-admin node instead. The owner-id node is optional. It specifies ID of the domain owner when the domain is created by Plesk Administrator or Plesk reseller. Data type: integer. Supported since protocol version 1.6.0.0. The owner-login node is optional. It specifies the login name of the domain owner when the domain is created by Plesk Administrator or Plesk reseller. Data type: string. Supported since protocol version 1.6.0.0. Note: If the information about owner is omitted, the domain account belongs to the user who issued the request.

The htype node is optional. It specifies one of the following hosting types: virtual hosting, standard forwarding, frame forwarding, none. Data type: string. Allowed values: vrt_hst | std_fwd | frm_fwd | none. Note: If you specify this node, you should also include the hosting node into the request packet.

The ip_address node is required. It specifies the IP address associated with the domain. Data type: ip_address (common.xsd). The status node is optional. It specifies the status of the created domain. Data type: string. Allowed values: 0 | 16 | 64. Meanings: 0 - active, 16 - disabled by Plesk Administrator, 32 - disabled by Plesk reseller, 64 - disabled by a client.

386

Supported Operations

The following packet creates a domain and sets all necessary general information for it:
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>example.com</name> <htype>vrt_hst</htype> <ip_address>192.0.2.11</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>c4u7dwbc2y8</ftp_login> <ftp_password>qweqwe</ftp_password> <ip_address>192.0.2.54</ip_address> </vrt_hst> </hosting> </add> </domain> </packet>

Supported Operations

387

Node gen_info (type domainGenInfoType)


Representation of gen_info in API RPC 1.4.2.0 and later versions This node is used in the get response packets. It is defined by complex type domainGenInfoType (plesk_domain.xsd) and holds a collection of common domain settings. Starting from API RPC 1.4.2.0, the gen_info node has got some changes as follows: The display_name node is now called name The name node was renamed into ascii-name

The cr_date node is required. It holds the creation date of the specified domain. Data type: date. Format: YYYY-MM-DD. The name node is required. It holds the domain name displayed in Plesk GUI. Data type: string. The ascii-name node is required. It holds the domain name in ASCII format. Data type: string. The status node is required. It holds the current status of the specified domain. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 4 (under backup/restore) | 16 (disabled by Plesk Administrator) | 32 (disabled by Plesk reseller) |64 (disabled by Plesk client) | 256 (expired).

388

Supported Operations

The real_size node is required. It holds the actual size of the domain (in bytes). Data type: unsignedLong. The client_id node is required. It holds the identifier of a Plesk client who owns this domain account. Data type: integer. Is not supported since protocol version 1.6.0.0. Use owner-id node instead. The owner-id node is optional. It holds the ID of Plesk user who owns this domain account. Must be specified if the request is issued by Plesk Administrator or Resellers. Data type: integer. Supported since protocol version 1.6.0.0. The dns_ip_address node is optional. It holds the domain IP address shown in the DNS record. Data type: ip_address (common.xsd). The htype node is required. It specifies the type of hosting set on the domain. Data type: string. Allowed values: vrt_hst | std_fwd | frm_fwd | none. The guid node is required. It contains the domain account GUID. Data type: string. This node is supported in API RPC 1.5.2.0 and later versions. For details on GUIDs, refer to the GUIDs Overview section of the API RPC Developer's Guide.

The following packet with general domain information can be received from Plesk server if API RPC 1.4.2.0 is used:
<packet version=1.6.0.0> <domain> <get> <result> <status>ok</status> <filter-id>1234</filter-id> <id>1234</id> <data> <gen_info> <cr_date>2000-12-12</cr_date> <name>www.example.com</name> <ascii-name>www.example.com</ascii-name> <status>256</status> <real_size>54687742156789</real_size> <owner-id>111</owner-id> <dns_ip_address>196.0.2.123</dns_ip_address> <htype>vrt_hst</htype> <guid>aasdgr342dsaddw3r32rsdfsdf3t</guid> </gen_info> </data> </result> </get> </domain> </packet>

This packet is specific for protocol version 1.4.2.0 and later: The response contains the filtering parameter (the filter-id node). The request packet filtered the domain by domain id, so the filter-id node of the response packet returns this filtering parameter, and the id node returns the domain identifier. Note that the earlier versions of API RPC protocol do not support this feature.

Supported Operations

389

Representation of gen_info in API RPC 1.4.1.2 and earlier versions In API RPC 1.4.1.2 and earlier, this node is structured as follows:

The cr_date node is required. It holds the creation date of the specified domain. Data type: date. Format: YYYY-MM-DD. The name node is required. It holds the domain name. Data type: string. The display_name node is required. It holds the domain name displayed in Plesk GUI. Data type: string. The status node is required. It holds the current status of the specified domain. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 4 (under backup/restore) | 16 (disabled by Plesk Administrator) | 64 (disabled by Plesk client) | 256 (expired). The real_size node is required. It holds the actual size of the domain (in bytes). Data type: unsignedLong. The client_id node is required. It holds the identifier of Plesk client who owns this domain account. Data type: integer. The dns_ip_address node is optional. It holds the domain's IP address shown in the DNS record. Data type: ip_address (common.xsd). The htype node is required. It specifies the type of hosting set on the domain. Data type: string. Allowed values: vrt_hst | std_fwd | frm_fwd | none.

390

Supported Operations

The following packet with general domain information can be received from Plesk server:
<packet version=1.4.1.2> <domain> <get> <result> <status>ok</status> <id>1234</id> <data> <gen_info> <cr_date>2000-12-12</cr_date> <name>alterzone.co.uk</name> <display_name>Error! Hyperlink reference not valid.> <status>256</status> <real_size>54687742156789</real_size> <client_id>111</client_id> <dns_ip_address>123.123.13.123</dns_ip_address> <htype>vrt_hst</htype> </gen_info> </data> </result> </get> </domain> </packet>

Node gen_setup (type setGenSetupType)


This node is used in the set request packets to set the general information for the specified domain(s). It is defined by data type setGenSetupType (plesk_domain.xsd). The gen_setup node is structured as follows:

The status node is optional. It is used to set the current status of the specified domain. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled by Plesk Administrator) | 32 (disabled by Plesk reseller) | 64 (disabled by Plesk client). The name node is optional. It is used to modify the domain name. Data type: string.

Supported Operations

391

The client_id node is optional. It is not supported since protocol version 1.6.0.0. Use owner-id or owned-login node instead. The owner-id node is optional. It specifies the ID of the new domain owner (Plesk Administrator, Plesk reseller, or Plesk client). Data type: integer. Supported since protocol version 1.6.0.0. The owner-login node is optional. It specifies the login name of the new domain owner (Plesk Administrator, Plesk reseller, or Plesk client). Data type: string. Supported since protocol version 1.6.0.0. The ip_address node is optional. It is used to modify the IP address associated with the domain. Data type: ip_address (common.xsd). The guid node is optional. If specified, the new GUID is assigned to the domain. This node is supported in API RPC 1.5.2.0 and later versions.For details on GUIDs, refer to the GUIDs Overview section of the API RPC Developer's Guide. Data type: boolean.

The following packet assigns all domains of one Plesk client (ID 1111) to another Plesk client (ID 1122). This packet can be sent by Plesk Administrator or Plesk reseller.
<packet version=1.6.0.0> <domain> <set> <filter> <owner-id>1111</owner-id> </filter> <values> <gen_setup> <status>0</status> <owner-id>1122</owner-id> <ip_address>192.0.2.121</ip_address> </gen_setup> </values> </set> </domain> </packet>

392

Supported Operations

Domain Administrator Settings


Domain Administrator settings are defined by two data types. Type domainUserSet (see page 392) is used in the add and set request packets Type domainUserGet (see page 394) is used in the get response packets

In this section:
Type domainUserSet......................................................................................... 392 Type domainUserGet ........................................................................................ 394

Type domainUserSet
The user node is used in the add and set request packets. It is specified by complex type domainUserSet (plesk_domain.xsd). This node is structured as follows (pareddown variant):

Supported Operations

393

The enabled node is optional. It specifies the domain account status. Data type: Boolean. The password node is optional. It specifies the domain administrator password. Data type: string (5 to 14 characters long). The global-login and the uid nodes are deprecated since protocol version 1.5.2.0. The cname node is optional. It specifies the company of a domain administrator. Data type: string (0 to 255 characters long). The pname node is optional. It specifies the domain administrator name. Data type: string (0 to 255 characters long). The phone node is optional. It specifies the phone number of a domain administrator. Data type: string (0 to 255 characters long). The fax node is optional. It specifies the fax number of a domain administrator. Data type: string (0 to 255 characters long). The email node is optional. It specifies the email address of a domain administrator. Data type: string (0 to 255 characters long). The address node is optional. It specifies the postal address of a domain administrator. Data type: string (0 to 255 characters long). The city node is optional. It specifies the domain administrator city. Data type: string (0 to 255 characters long). The state node is optional. It specifies the domain administrator state. Is required for US only. Data type: string (0 to 255 characters long). The pcode node is optional. It specifies the zip code of a domain administrator. Is required for US only. Data type: string (0 to 10 characters long). The country node is optional. It specifies the country code of a domain administrator. Data type: string (0 to 2 characters long). The multiply_login node is optional. It indicates whether multiple logins with the same domain administrator credentials are allowed. Data type: Boolean. The perms node is optional. It specifies a collection of permissions set for the domain administrator. Data type: domainPerms (plesk_domain.xsd). To view the structure of this node, refer to the Limits, Permessions and Hosting Settings (see page 397) section.

394

Supported Operations

The following sample packet creates a domain account and sets Domain Administrator information:
<packet version=1.6.0.0> <domain> <add> <gen_setup> <name>example.com</name> <owner-id>1234</owner-id> <ip_address>192.0.2.123</ip_address> </gen_setup> <user> <enabled>false</enabled> <password>123456</password> <cname>Mega Company</cname> <pname>John Doe</pname> <phone>2121342526</phone> <fax>2121342527</fax> <email>JDoe@sample.com</email> <address>Gray Lake Road, 12</address> <city>Totonto</city> <state/> <pcode/> <country>CA</country> <multiply_login>false</multiply_login> <permissions/> </user> </add> </domain> </packet>

Supported Operations

395

Type domainUserGet
The user node used in the get response packets is specified by complex type domainUserGet (plesk_domain.xsd). It is structured as follows:

The enabled node is optional. It shows whether the domain account is enabled. Data type: Boolean. The cname node is optional. It specifies the company where the domain administrator works. Data type: string (0 to 255 characters long). The pname node is optional. It specifies the name of the domain administrator. Data type: string (0 to 255 characters long). The phone node is optional. It specifies the phone number of the domain administrator. Data type: string (0 to 255 characters long). The fax node is optional. It specifies the fax number of the domain administrator. Data type: string (0 to 255 characters long). The email node is optional. It specifies the email address of the domain administrator. Data type: string (0 to 255 characters long). The address node is optional. It specifies the postal address of the domain administrator. Data type: string (0 to 255 characters long).

396

Supported Operations

The city node is optional. It specifies the city of the domain administrator. Data type: string (0 to 255 characters long). The state node is optional. It specifies the state of the domain administrator. Is required for US only. Data type: string (0 to 255 characters long). The pcode node is optional. It specifies the zip code of the domain administrator. Is required for US only. Data type: string (0 to 10 characters long). The country node is optional. It specifies the country code of the domain administrator. Data type: string (0 to 2 characters long). The multiply_login node is optional. It indicates whether multiple logins are allowed under the same domain administrator credentials. Data type: Boolean. The perms node is optional. It specifies a collection of permissions set for the domain administrator. Data type: domainPerms (plesk_domain.xsd). See the structure of this node in the Limits, Permissions and Hosting Settings (see page 397) section. The global-login and the uid nodes are deprecated since protocol version 1.5.2.0.

The following response packet demonstrates the domain administrator information returned from Plesk server:
<packet version=1.4.2.0> <domain> <get> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> <data> <user> <enabled>true</enabled> <cname>Mega Company</cname> <pname>John Doe</pname> <phone>2121342526</phone> <fax>2121342527</fax> <email>JDoe@sample.com</email> <address>Gray Lake Road, 12</address> <city>Totonto</city> <state> </state> <pcode> </pcode> <country>CA</country> <multiply_login>false</multiply_login> <permissions> </permissions> </user> </data> </result> </get> </domain> </packet>

This packet is specific for API RPC 1.4.2.0: the response contains the filtering parameter (the filter-id node). The request packet filtered the domain by domain ID, so the filter-id node of the response packet returns this filtering parameter, and the id node returns the domain identifier. Note that the earlier versions of API RPC protocol do not support this feature.

Supported Operations

397

Limits, Permissions and Hosting Settings


This section contains limits and permissions settings for domain administrators. Starting from API RPC 1.5.0.0 you can manage the settings using descriptors. For details on descriptors, refer to the Presentation of Object Descriptor (on page 47) section in API Reference, or to the API RPC Protocol Developer's Guide.

In this section:
API RPC 1.5.0.0 and Later Versions ................................................................. 397 API RPC 1.4.2.0 and Earlier Versions ............................................................... 400

API RPC 1.5.0.0 and Later Versions


This section contains domain limits and domain administrator permissions' settings, that are available in API RPC v.1.5.0.0 and later.

In this section:
Limits................................................................................................................. 397 Permissions....................................................................................................... 398 Hosting Settings ................................................................................................ 399

Limits
The limits node is presented by domainLimits type (plesk_domain.xsd), and its graphical representation is as follows:

The overuse node is optional. It specifies the limits overusage policy for a specified domain. Data type: string. Allowed values: block | notify | normal. The node is supported since protocol version 1.6.0.0.

398

Supported Operations

The limit node is optional. It specifies limit parameters. Data type: PleskLimitType (plesk_client.xsd). The name node is required. It specifies limit name. Data type: sting. The value node is required. It specifies limit value. Data type: any.

Note: You can specify multiple limit parameters within one limits node. The following code example specifies the limits overusage policy and the mailbox quota limit:
<limits> <overuse>block</overuse> <limit> <name>mbox_quota</name> <value>100</value> </limit> </limits>

Note: To manage limits, you should first retrieve limits descriptor, containing names of limits. For details, refer to the Retrieving Descriptor of Limits (on page 472) section.

Permissions
The perms node is presented by the domainPerms complex type (plesk_domain.xsd), and its graphical representation is as follows:

The permission node is required. It specifies parameters of a permission. Data type: PleskPermissionType (plesk_common.xsd). The name node is required. It specifies a permission name. Data type: sting. The value node is required. It specifies a permission value. Data type: any.

Note: You can specify multiple permission parameters in one perms node.

Supported Operations

399

The following code represents permission to access shell:


<permissions> <permission> <name>manage_sh_access</name> <value>100</value> </permission> ... </permissions>

Note: To manage preferences, you should first retrieve permissions descriptor, containing names of permissions. For details, refer to the Retrieving Descriptor of Permissions (on page 478) section.

Hosting Settings
The hosting node in API RPC 1.5.0.0 and later versions is the same as in API RPC 1.4.2.0 except for the vrt_hst node. For details on the hosting node, refer to the Hosting Settings (see page 397) (API RPC 1.4.2.0) section. The graphical representation of the vrt_hst node (API RPC 1.5.0.0) is as follows:

The property node is required. It specifies a hosting parameter. Data type: PleskPhysHostingPropertyType (plesk_domain.xsd). The name node is required. It specifies a hosting parameter name. Data type: sting. The value node is required. It specifies a hosting parameter value. Data type: any.

Note: You can specify multiple property parameters in one vrt_hst node. The ip_address node is required. It specifies the IP address of the domain. Data type: ip_address (common.xsd).

400

Supported Operations

The following code represents FTP login parameter:


<vrt_hst> <property> <name>ftp_login</name> <value>MyFTPlogin</value> </property> ... </vrt_hst>

Note: To manage hosting settings, you should first retrieve a hosting settings descriptor, containing names of the settings. For details, refer to the Retrieving Descriptor of Hosting Settings (on page 482) section.

API RPC 1.4.2.0 and Earlier Versions

This section contains domain limits and domain administrators' permissions settings, that are available in API RPC v.1.4.2.0 and earlier.

In this section:
Limits................................................................................................................. 401 Permissions....................................................................................................... 403 Hosting Settings ................................................................................................ 407

Supported Operations

401

Limits
Limits imposed on use of system resources are defined by the limits node. This node is specified by complex type domainLimits (plesk_domains.xsd). It is structured as follows:

The max_webapps node is optional. Specifies the maximum number of web applications allowed on the domain. Data type: integer. The max_maillists node is optional. Specifies the maximum number of mailing lists on the domain. Data type: integer.

402

Supported Operations

The max_resp node is optional. Specifies the maximum number of autoresponders (preset messages sent automatically) on the domain. Data type: integer. The max_mg node is optional. Specifies the maximum number of mail groups on the domain. Data type: integer. The max_redir node is optional. Specifies the maximum number of redirects on the domain. Data type: integer. The mbox_quota node is optional. Restricts the maximum amount of disk space (in bytes) allotted for a single mailbox on the domain. Data type: integer. The max_box node is optional. Specifies the maximum number of email boxes on the domain. Data type: integer. The max_db node is optional. It specifies the maximum number of MySQL databases for the domain. Data type: integer. The max_wu node is optional. Specifies the maximum number of web pages (web users) hosted on the domain. Data type: integer. The max_traffic node is optional. Specifies the maximum data traffic per month (in bytes) for the domain. Data type: integer. The disk_space node is optional. Restricts the amount of disk space (in bytes) for the domain. Data type: integer. The max_subdom node is optional. Specifies the maximum number of subdomains that can be created on the domain. Data type: integer. The expiration node is optional. Specifies the validity period for the domain account. Data type: integer (a UNIX timestamp format). The max_dom_aliases node is optional. Specifies the maximum number of aliases for the domain. Data type: integer. The total_mboxes_quota node is optional. Restricts the maximum amount of disk space (in bytes) occupied by all mail boxes on the domain. Data type: integer. Is used for Plesk for Windows only. The mysql_dbase_space node is optional. Sets the disk space limit (in bytes) on MySQL databases belonging to the domain. Data type: integer. The mssql_dbase_space node is optional. Sets the disk space limit (in bytes) on Microsoft SQL databases belonging to the domain. Data type: integer. Is used for Plesk for Windows only. The max_mssql_db node is optional. Limits the number of Microsoft SQL databases for the domain. Data type: integer. Is used for Plesk for Windows only. The max_shared_ssl_links node is optional. Specifies the maximum number of shared SSL links for the domain. Data type: integer.

Supported Operations

403

The max_subftp_users node is optional. Specifies the maximum number of additional FTP accounts on the domain. Data type: integer. Is used for Plesk for Windows only. The max_fpse_users node is optional. Specifies the maximum number of additional MS FrontPage accounts on the domain. Data type: integer. Is used for Plesk for Windows only. The max_odbc node is optional. Specifies the maximum number of ODBC connections allowed on the domain. Data type: integer. Is supported by API RPC 1.4.2.0 and later. Is used for Plesk for Windows only.

Note: The limits on Plesk resources set for the domain account are restricted by similar limits set for the parent client account. The following sample packet creates a domain account and limits the use of Plesk resources for this domain:
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <ip_address>192.0.2.123</ip_address> </gen_setup> <limits> <disk_space>209715200</disk_space> <max_traffic>209715200</max_traffic> <max_subdom>20</max_subdom> <max_wu>10000</max_wu> <max_subftp_users>10000</max_subftp_users> <max_db>100</max_db> <mysql_dbase_space>52428800</mysql_dbase_space> <max_mssql_db>100</max_mssql_db> <mysql_dbase_space>52428800</mysql_dbase_space> </limits> </add> </domain> </packet>

Permissions
The perms node is specified by complex type domainPerms (plesk_domain.xsd). It is structured as follows:

404

Supported Operations

Supported Operations

405

The manage_phosting node is optional. It indicates whether the domain administrator can manage physical hosting parameters of the domain. Data type: Boolean. The manage_quota node is optional. It indicates whether the domain administrator can change the hard disk quota set for the domain. Data type: Boolean. The manage_subdomains node is optional. It indicates whether the domain administrator can manage subdomains created on the domain. Data type: Boolean. The manage_not_chroot_shell node is optional. It indicates whether the domain administrator can manage non-chrooted shell access. Data type: Boolean. The manage_dns node is optional. It indicates whether the domain administrator can manage DNS settings on the domain. Data type: Boolean. The manage_log node is optional. It indicates whether the domain administrator can manage logging on the domain. Data type: Boolean. The manage_crontab node is optional. It indicates whether the domain administrator can manage the task scheduler on the domain. Data type: Boolean. The manage_anonftp node is optional. It indicates whether the domain administrator can manage anonymous FTP account settings on the domain. Data type: Boolean. The manage_webapps node is optional. It indicates whether the domain administrator can manage Tomcat web applications installed on the domain. Data type: Boolean. The manage_sh_access node is optional. It indicates whether the domain administrator can manage system shell access on the domain. Data type: Boolean. The manage_maillists node is optional. It indicates whether the domain administrator can manage mailing lists on the domain. Data type: Boolean. The manage_drweb node is optional. It indicates whether the domain administrator can manage DrWeb antivirus software on the domain (if supported by the key). Data type: Boolean. The make_dumps node is optional. It indicates whether the domain administrator can make dumps of the domain using backup/restore facilities of Plesk. Data type: Boolean. The site_builder node is optional. It indicates whether the domain administrator can use SiteBuilder. Data type: Boolean . This feature is not supported on Plesk 8.0 for Unix and later. The manage_ftp_password node is optional. It indicates whether the domain administrator can change the password of the FTP account on the domain. Data type: Boolean. The manage_performance node is optional. It indicates whether the domain administrator can manage hosting performance on the domain. Data type: Boolean. The manage_domain_aliases node is optional. It indicates whether the domain administrator can manage domain aliases. Data type: Boolean. The manage_iis_app_pool node is optional. It indicates whether the domain administrator can manage IIS application pool settings on the domain. Data type: Boolean. The dashboard node is optional. It indicates whether the domain administrator can manage the domain via Plesk desktop. Data type: Boolean. The stdgui node is optional. It indicates whether the domain administrator can use the standard GUI of Plesk. Data type: Boolean. The manage_dashboard node is optional. It indicates whether the domain administrator can customize Plesk desktop. Data type: Boolean.

406

Supported Operations

The manage_subftp node is optional. It indicates whether the domain administrator can manage additional FTP accounts created on the domain. Data type: Boolean. The element is supported beginning with version 1.4.1.0 of API RPC. The manage_spamfilter node is optional. It indicates whether the domain administrator can manage the spam filter. Data type: Boolean. Is supported by API RPC 1.4.2.0 and later. Is used for Plesk for UNIX only. The allow_local_backups node is optional. It indicates whether the domain administrator can use the local repository for backup/restore operations. Data type: Boolean. Is supported by API RPC 1.4.2.0 and later. Is used for Plesk for UNIX only. The allow_ftp_backups node is optional. It indicates whether the domain administrator can use the FTP repository for backup/restore operations. Data type: Boolean. Is supported by API RPC 1.4.2.0 and later.

The following sample packet creates a domain account and sets Domain Administrator information and permissions:
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <ip_address>192.0.2.123</ip_address> </gen_setup> <user> <enabled>true</enabled> <password>123456</password> <cname>technolux</cname> <pname>Stephen Holmes</pname> <phone>2121342526</phone> <fax>2121342527</fax> <email>sholmes@technolux.ca</email> <address>Gray Lake Road, 12</address> <city>Totonto</city> <state/> <pcode/> <country>CA</country> <multiply_login>false</multiply_login> <permissions> <manage_quota>true</manage_quota> <manage_subdomains>true</manage_subdomains> <manage_anonftp>true</manage_anonftp> <manage_webapps>true</manage_webapps> <manage_maillists>true</manage_maillists> <manage_drweb>true</manage_drweb> <make_dumps>true</make_dumps> <manage_ftp_password>true</manage_ftp_password> <manage_performance>true</manage_performance> <manage_domain_aliases>true</manage_domain_aliases> <dashboard>true</dashboard> <manage_dashboard>true</manage_dashboard> <manage_subftp>true</manage_subftp> <allow_ftp_backups>true</allow_ftp_backups> </permissions> </user></add></domain></packet>

Supported Operations

407

Hosting Settings
Hosting settings are described by two data types. Complex type domainHostingAgentSet is used in the add and set request packets. Complex type domainHostingAgentGet is used in the get response packets.

Both data types are similar, except they specify their vrt_hst nodes using different data types: The vrt_hst node is required if physical hosting is specified on the domain. Data type: none. Extended by: domainPhHostingSet (plesk_domain.xsd). See the structure of this node in the Node vrt_hst (type domainPhHostingSet) (see page 409) subtopic. The vrt_hst node is required if physical hosting is specified on the domain. Data type: none. Extended by: domainPhHostingGet (plesk_doman.xsd). See the structure of this node in the Node vrt_hst (type domainPhHostongGet) sub-topic.

The std_fwd node is required if standard forwarding is specified on the domain. Data type: none. Extended by: domainFFHostingBase (plesk_domain.xsd). See the structure of this node in the Node std_fwd (see page 413) sub-topic. The frm_fwd node is required if frame forwarding is specified on a domain. Data type: none. Extended by: domainSFHostingBase (plesk_domain.xsd). See the structure of this node in the Node frm_fwd (see page 414) sub-topic. The none node is required if no hosting is specified on a domain. If specified, hosting settings will be deleted. Data type: none.

408

Supported Operations

The following request add packet sent by Administrator creates a domain with disabled hosting :

<packet version=1.4.1.2> <domain> <add> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <status>0</status> </gen_setup> <hosting> <none/> </hosting> </add> </domain> </packet>

In this section:
Node vrt_hst (type domainPhHostingSet) .......................................................... 409 Node std_fwd .................................................................................................... 413 Node frm_fwd .................................................................................................... 414

Supported Operations

409

Node vrt_hst (type domainPhHostingSet)


The vrt_hst node is used in the add and set request packets. It is presented by complex type domainPhHostingSet. This node is structured as follows:

410

Supported Operations

The ftp_login node is required. It specifies the login name of the FTP account created on the domain. Data type: string (1 to 17 characters long, allowed characters: a-z, A-Z, 0-9, _, .). The ftp_password node is required. It specifies the password of the FTP account created on the domain. Data type: string (up to 64 characters long, not equal to FTP login). The ftp_quota node is optional. It restricts the disk space (in bytes) allotted for FTP needs on the domain. Data type: integer. For details on unlimited values for FTP quota, refer to the table below. The fp node is optional. It enables/disables FrontPage support on the domain. Data type: Boolean. The fp_ssl node is optional. It enables/disables support for FrontPage via SSL. Data type: Boolean. The fp_auth node is optional. It allows/disallows authoring using FrontPage on the domain. Data type: Boolean. The fp_admin_login node is optional. It specifies the login name of the FrontPage administrator (if FP is supported on the domain). Data type: string (up to 16 characters long). The fp_admin_password node is optional. It specifies the password of the FrontPage administrator (if FP is supported on the domain). Data type: string (up to 20 characters long). The ssl node is optional. It indicates whether the domain is accessed via SSL connection. Data type: Boolean. The shell node is optional. It allows/disallows shell access to Plesk with FTP user login credentials. Data type: string (up to 255 characters long). Allowed values in UNIX: the default value (/bin/false) disables shell access. A path of a shell command interpreter (like /bin/sh or /bin/bash) allows shell access. Allowed values in Windows: Login Enabled | Login Disabled. Starting with API RPC v.1.4.1.0, you can choose between nodes <shell> and <shell-forbidden> (the latter node prohibits shell access to Plesk). The shell-forbidden node is optional. It is used to prohibit shell access to Plesk for FTP users of the domain. Data type: none. This node is used in API RPC 1.4.1.0 and higher. The php node is optional. It enables/disables PHP support on the domain. Data type: Boolean. The php_isapi node in optional. If set to true, it indicates that PHP scripts are executed by IIS as ISAPI extensions (otherwise they are executed as CGI applications). Data type: Boolean. This parameter makes sense for Plesk for Windows only. It is supported by API RPC beginning with version 1.4.1.0. The ssi node is optional. It enables/disables SSI support on the domain. Data type: Boolean. The ssi_html node is optional. If set to true, it indicates that the web server should look in HTML and HTM files for SSI scenarios (they are normally used in SHTML, SHTM, STM files). Data type: Boolean. This parameter makes sense for Plesk for Windows only. It is supported by API RPC beginning with version 1.4.1.0. The cgi node is optional. It enables/disables CGI support on the domain. Data type: Boolean. The mod_perl mode is optional. It enables/disables Perl support on the domain. Data type: Boolean.

Supported Operations

411

The mod_python node is optional. It enables/disables Python support on the domain. Data type: Boolean. The asp node is optional. It enables/disables Apache ASP support on the domain. Data type: Boolean The asp_dot_net node is optional. It enables/disables support for ASP.NET on the domain. Data type: Boolean. This parameter makes sense for Plesk for Windows only. The managed_runtime_version node is optional. It specifies ASP.NET version which is default for the domain. Data type: string. Allowed values: 1.0 | 2.0. This parameter makes sense for Plesk for Windows only. It is supported by API RPC beginning with version 1.4.0.0 The coldfusion node is optional. It enables/disables Coldfusion support on the domain. Data type: Boolean. The webstat node is optional. It specifies the web server statistics processor to be used on the domain. Data type: string. Allowed values: none | awstats | webalizer | smarterstats | urchin. The webstat_protected node is optional. If set to true, indicates that statistics is accessible via a password protected directory (/plesk-stat/). Data type: Boolean. The errdocs node is optional. If set to true, indicates that the use of custom error documents is enabled on the domain. Data type: Boolean. The wuscripts node is optional. Indicates whether web user scripts are allowed for execution on the domain. Data type: Boolean. Is supported by API RPC 1.4.2.0 and later. The at_domains node is optional. It enables/disables support for the @<domain_name> format on the domain. Data type: Boolean. The sb_publishing node is optional. It enables/disables publishing web site on the domain using SiteBuilder. Data type: Boolean. This element is supported starting with API RPC v.1.4.2.0. Makes sense for Plesk for Windows only. The php_safe_mode node is optional. It enables/disables executing php script files in the safe mode on the domain. Data type: Boolean. The iis_app_pool node is optional. It enables/disables IIS application pool on the domain. Data type: Boolean. This element is supported beginning with version 1.4.1.0 of API RPC. Makes sense for Plesk for Windows only. The fastcgi node is optional. It indicates whether the FastCGI technology is supported on the domain. Data type: Boolean. This feature is supported by API RPC 1.4.2.0 and later. Makes sense for Plesk for UNIX only. The php-version node is optional. It specifies what version of PHP should be default for domain directory. Data type: string. Allowed values: 4 | 5. This element is supported starting with API RPC v.1.4.2.0. Makes sense for Plesk for Windows only. The create-sb-subdomains node is optional. It specifies if the SiteBuilder blog and photo gallery subdomains should be created on the domain. Data type: boolean. This element is supported starting with API RPC v.1.4.2.0. Makes sense for Plesk for Windows only. The ip_address node is required. It specifies the IP address associated with the domain. Data type: ip_address (common.xsd).

412

Supported Operations

Values for unlimited FTP quota parameter.


API RPC 1.4.2.0 and earlier Plesk for Windows Plesk for Unix 0 -1 API RPC 1.5.0.0 and later -1 -1

The following sample packet creates a new domain and specifies physical hosting settings for it:
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <ip_address>123.123.123.123</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>ftpuser</ftp_login> <ftp_password>12345</ftp_password> <php>true</php> <ssi>true</ssi> <cgi>true</cgi> <php_safe_mode>true</php_safe_mode> <ip_address>123.123.123.123</ip_address> </vrt_hst> </hosting> </add> </domain> </packet>

If the gen_setup node specifies an IP address and the hosting node indicates a different IP address then the second IP address will be valid.

Supported Operations

413

Node std_fwd
The std_fwd node is used to specify standard forwarding on a domain. When the user goes to the domain on which standard forwarding is set, Plesk redirects this user from the requested URL to the destination URL. This is done explicitly: the user sees the real destination address in the path bar of the browser. The std_fwd node is structured as follows:

The dest_url node is required. It specifies the URL to which the user will be redirected explicitly at the attempt to visit the specified domain. Data type: forwardingUrl (string, 1 to 255 characters long, spaces not allowed). The ip_address node is required. It specifies the IP address associated with the domain. Data type: ip_address (common.xsd).

The following sample packet specifies standard forwarding for a new domain:
<packet version=1.4.1.2> <domain> <add> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <ip_address>123.123.123.123</ip_address> <status>0</status> </gen_setup> <hosting> <std_fwd> <dest_url>www.olddomain.com</dest_url> <ip_address>123.123.123.123</ip_address> </std_fwd> </hosting> </add> </domain> </packet>

414

Supported Operations

Node frm_fwd
The frm_fwd node is used to specify frame forwarding on a domain. When the user goes to the domain on which frame forwarding is set, Plesk redirects this user from the requested URL to the destination URL implicitly (the user still sees the initial URL in the path bar of the browser).

The dest_url node is required. It specifies the URL to which the user will be redirected implicitly at the attempt to visit the specified domain. Data type: forwardingUrl (string, 1 to 255 characters long, spaces not allowed). The ip_address node is required. It specifies the IP address associated with the domain. Data type: ip_address (common.xsd).

The following sample packet specifies frame forwarding for a new domain:
<packet version=1.4.1.2> <domain> <add> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <ip_address>123.123.123.123</ip_address> <status>0</status> </gen_setup> <hosting> <frm_fwd> <dest_url>www.testdomain.com</dest_url> <ip_address>123.123.123.123</ip_address> </frm_fwd> </hosting> </add> </domain> </packet>

Supported Operations

415

Disk Space Usage Settings


Disk usage settings restrict the amount of disk space set for various entities (logs, folders, databases, etc.) on a domain. To get these settings from Plesk database, send the get packet and receive the response. The returned disk_usage node has no data type, it is nested within the data node (described in plesk_domain.xsd) and has the following structure.

The httpdocs node is required. Specifies the amount of disk space (in bytes) occupied by the /httpdocs directory. Data type: long. The httpsdocs node is required. Specifies the amount of disk space (in bytes) occupied by the /httpsdocs directory. Data type: long. The subdomains node is required. Specifies the amount of disk space (in bytes) occupied by subdomains of this domain. Data type: long. The web_users node is required. Specifies the amount of disk space (in bytes) allotted for web users on the domain. Data type: long. The anonftp node is required. Specifies the amount of disk space (in bytes) occupied by anonymous FTP. Data type: long.

416

Supported Operations

The logs node is required. Specifies the amount of disk space (in bytes) occupied by logs. Data type: long. The dbases node is required. Specifies the amount of disk space (in bytes) occupied by databases created for the domain. Data type: long. Makes sense for Plesk for UNIX only. The mysql_dbases node is required. Specifies the amount of disk space (in bytes) occupied by MySQL databases created for the domain. Data type: integer. Makes sense for Plesk for Windows only. The mssql_dbases node is required. Specifies the amount of disk space (in bytes) occupied by MSSQL databases created for the domain. Data type: integer. Makes sense for Plesk for Windows only. The mailboxes node is required. Specifies the amount of disk space (in bytes) allotted by mailboxes of the domain. Data type: long. The webapps node is required. Specifies the amount of disk space (in bytes) occupied by Tomcat web applications deployed on the domain. Data type: long. The maillists node is required. Specifies the amount of disk space (in bytes) occupied by mailing lists created on the domain. Data type: long. The domaindumps node is required. Specifies the amount of disk space (in bytes) occupied by dumps of the domain. Data type: long. The configs node is required. Specifies the amount of disk space (in bytes) occupied by configuration files of the domain. Data type: long. Makes sense for Plesk for UNIX only. It is supported beginning with API RPC 1.3.5.0. The chroot node is required. Specifies the amount of disk space (in bytes) occupied by the /chroot directory on the domain. Data type: long. Makes sense for Plesk for UNIX only. It is supported beginning with API RPC 1.3.5.0.

Most of these settings cannot be set up directly. You can set only two of them: mailboxes and maillists. The disk_usage node of the set request packet does not have its own data type and is structured as follows:

The mailboxes node is optional. Specifies the amount of disk space (in bytes) allotted by mailboxes of the domain. Data type: long. The maillists node is optional. Specifies the amount of disk space (in bytes) occupied by mailing lists created on the domain. Data type: long.

Supported Operations

417

The following set request packet sets the limits on the hard disk space for email boxes and mailing lists:
<packet version=1.4.2.0> <domain> <set> <filter> <id>123</id> <id>124</id> </filter> <values> <disk_usage> <mailboxes>1073741824</mailboxes> <maillists>1048576</maillists> </disk_usage> </values> </set> </domain> </packet>

The following get response packet returns the disk usage information for the specified domain:
<packet version=1.4.2.0> <domain> <get> <result> <status>ok</status> <filter-id>technolux.co.uk</filter-id> <id>2435</id> <data> <disk_usage> <httpdocs>2097152</httpdocs> <httpsdocs>1572864</httpsdocs> <subdomains>12582945</subdomains> <web_users>130023456</web_users> <anonftp>12582975</anonftp> <logs>4194312</logs> <dbases>4194325</dbases> <mailboxes>12582978</mailboxes> <webapps>3145728</webapps> <maillists>1048523</maillists> <domaindumps>209715200</domaindumps> <configs>25078</configs> <chroot>2095647</chroot> </disk_usage> </data> </result> </get> </domain> </packet>

This packet is specific for API RPC 1.4.2.0: the response contains the filtering parameter (the filter-id node). The request packet filtered the domain by domain name, so the filter-id node of the response packet returns this filtering parameter, and the id node returns the domain identifier. Note that the earlier versions of API RPC protocol do not support this feature.

418

Supported Operations

Statistics Settings
Statistics settings can be received from Plesk server in the get response packet. The stat node of the get response packet is defined by the domainStat data type (plesk_domain.xsd) and contains a collection of statistics data for the specified domains. This node is structured as follows:

The traffic node is required. It returns the traffic (in bytes) spent by the domain during the current month. Data type: size (unsignedLong). The subdom node is required. It holds the number of subdomains created on the domain. Data type: unsignedInt. The wu node is required. It holds the number of web users created on the domain. Data type: unsignedInt. The box node is required. It holds the number of email boxes created for the domain. Data type: unsignedInt. The redir node is required. It returns the number of redirects created for the domain. Data type: unsignedInt.

Supported Operations

419

The mg node is required. It returns the number of mailing groups created on the domain. Data type: unsignedInt. The resp node is required. It returns the number of autoresponders created on the domain. Data type: unsignedInt. The maillists node is required. It returns the number of mailing lists created on the domain. Data type: unsignedInt. The db node is required. It holds the number of databases created for the domain. Data type: unsignedInt. The webapps node is required. It returns the number of Java applications installed on the domain. Data type: unsignedInt. The traffic_prevday node is required. It returns the traffic (in bytes) spent by the domain during the previous day. Data type: unsignedLong.

The following response packet returns statistics settings for two filtered domains (ID 2435 and ID 2567):
<packet version=1.4.2.0> <domain> <get> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> <data> <stat> <traffic>12458966221478885</traffic> <subdom>12</subdom> <wu>134</wu> <box>1024</box> <redir>2</redir> <mg>16</mg> <resp>124</resp> <maillists>4<maillists> <db></db> <webapps>8</webapps> <traffic_prevday>15241632184739856</traffic_prevday> </stat> </data> </result> <result> <status>ok</status> <filter-id>2567</filter-id> <id>2567</id> <data> <stat> <traffic>5896615637124</traffic> <subdom>10</subdom> <wu>18</wu> <box>102</box> <redir></redir> <mg>11</mg> <resp>12</resp> <maillists>6<maillists> <db>2</db> <webapps>5</webapps>

420

Supported Operations <traffic_prevday>152562874868127</traffic_prevday> </stat> </data> </result> </get> </domain> </packet>

This packet is specific for API RPC 1.4.2.0: the response contains the filtering parameter (the filter-id node). The request packet filtered the domain by domain ID, so the filter-id node of the response packet returns this filtering parameter, and the id node returns the domain identifier. Note that the earlier versions of API RPC protocol do not support this feature.

Domain Preferences
Domain preferences are defined by the prefs node. This node is specified by the domainPrefs (plesk_domain.xsd). It is structured as follows:

The www node is optional. It enables/disables the use of the www prefix with the domain name. Data type: Boolean. The stat_ttl node is optional. It specifies the number of months during which the domain traffic statistics is kept. Data type: integer. The maximal value: 999999.

The following sample packet creates a domain account and sets domain preferences:
<packet version=1.6.0.0> <domain> <add> <gen_setup> <name>example.com</name> <owner-id>1234</owner-id> <ip_address>192.0.2.123</ip_address> </gen_setup> <prefs> <www>false</www> <stat_ttl>6</stat_ttl> </prefs> </add> </domain> </packet>

Supported Operations

421

Performance Settings
Domain performance settings are defined by the performance node. This node is specified by complex type DomainPerformanceType (plesk_domain.xsd). This type is structured as follows:

The bandwidth node is optional. It restricts the network use by the specified value (Kb/sec) for the domain. Data type: integer. If set to -1, the bandwidth is unlimited. Note: If you work with Plesk for Unix/Linux through API RPC 1.5.2.1 or earlier versions, you must provide bandwidth values in bytes/sec.

The max_connections node is optional. It restricts the number of connections by the specified value for the domain. Data type: integer. If set to -1, the number of connections is unlimited.

Note: All operations on domain performance settings are supported in API RPC beginning with version 1.4.1.0. The following sample packet creates a domain account and sets performance settings:
<packet version=1.6.0.0> <domain> <add> <gen_setup> <name>newdomain.com</name> <owner-id>1234</owner-id> <ip_address>192.0.2.123</ip_address> </gen_setup> <performance> <bandwidth>1000</bandwidth> <max_connections>20</max_connections> </performance> </add> </domain> </packet>

422

Supported Operations

To undo the performance settings for this domain, send a packet as follows:
<packet version=1.6.0.0> <domain> <set> <filter> <domain-name>example.com</domain-name> </filter> <values> <performance> <bandwidth>-1</bandwidth> <max_connections>-1</max_connections> </performance> </values> </set> </domain> </packet>

Creating Domain Account


A domain account can be created by Plesk Administrator, Plesk reseller or Plesk client. To register a new domain account in Plesk database, it is enough to specify some general setup information, namely: the domain name, and the IP address. If the domain is created by Plesk Administrator or Plesk reseller, the domain owner needs to be specified too. In addition, you can specify various domain settings when creating a domain account (all of them are optional): Hosting settings (see page 397) Hosting performance settings (see page 421) Limits (see page 397) on use of Plesk resources Domain preferences (see page 420) Domain administrator settings (see page 392) Domain template

A domain account can have all these settings specified, or it can hold just some of them. You can specify domain settings when creating a domain account or later (they can be set using the set operation). The only exception from this rule is a domain template: it cannot be applied to the domain after it is created. To learn more about the domain templates management via API RPC, proceed to section Managing Domain Templates (see page 516).

In this section:
Request Packet Structure.................................................................................. 423 Request Samples .............................................................................................. 425 Response Packet Structure ............................................................................... 427 Response Samples ........................................................................................... 428

Supported Operations

423

Request Packet Structure


A request XML packet adding a new domain account to Plesk database includes the add operation node:
<packet version=1.4.2.0> <domain> <add> </add> </domain> </packet>

The add node does not have a separate type, it is nested within type DomainTypeRequest (domain_input.xsd). The add node has the following graphics representation:

The gen_setup node is required. It is used to specify the most important information about the domain account, that is: the name of the new domain, the Plesk user who owns this domain, the hosting type used for this domain, the IP address associated with the domain, and the status got by the domain right after it is created. Data type: setGenSetupType (plesk_domain.xsd). See the structure of this node in the General Account Information (see page 385) section. The hosting node is optional. It specified hosting settings set for the domain. Data type: domainHostingAgentSet (plesk_domain.xsd). See the structure of this node in the Hosting Settings (see page 397) section. The limits node is optional. It specifies limits imposed on use of Plesk resources for this domain. Data type: domainLimits (plesk_domain.xsd). See the structure of this node in the Limits (see page 397)section. The prefs node is optional. It specifies a collection of domain preferences. Data type: domainPrefs (plesk_domain.xsd). See the structure of this node in the Domain Preferences (see page 420) section.

424

Supported Operations

The user node is optional. Is specifies Domain Administrator settings (login, password, phone, fax, email address, postal address, and so on.). Data type: domainUserSet (plesk_domain.xsd). See the structure of this node in the Domain Administrator Settings (see page 392) section.

The performance node is optional. It specifies a collection of domain performance settings (bandwidth, the maximal number of connections). Data type: DomainPerformanceType (plesk_domain.xsd). This node is available in API RPC 1.4.1.0 and later. See the structure of this node in the Performance Settings (see page 421) section.

The template-id node is optional. It specifies the domain template by ID if it is necessary to create a domain using a domain template. Data type: integer. This node is available in API RPC 1.4.1.0 and later. To learn more about domain templates, proceed to section Managing Domain Templates (see page 516).

The template-name node is optional. It specifies the domain template by name if it is necessary to create a domain using a domain template. Data type: string. This node is available in API RPC 1.4.1.0 and later. To learn more about domain templates, proceed to section Managing Domain Templates (see page 516). Note: You can use only templates to which the domain account owner has access. For instance, Plesk Administrator can use only shared templates to create domain accounts for clients.

Supported Operations

425

Request Samples
Creating domain accounts under different Plesk users Domain accounts can be created by Plesk Administrator, Plesk resellers or Plesk clients. Here is a sample request packet that can be used by a Plesk client to create a domain account. The domain account is created with a minimal collection of settings.
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>example.com</name> <htype>vrt_hst</htype> <ip_address>192.0.2.123</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>c4u7dwbc2y8</ftp_login> <ftp_password>qweqwe</ftp_password> <ip_address>192.0.2.54</ip_address> </vrt_hst> </hosting> </add> </domain> </packet>

The following packet sent by Plesk Administrator specifies the Plesk user who owns this domain:
<packet version=1.6.0.0> <domain> <add> <gen_setup> <name>newdomain.com</name> <owner-id>1234</owner-id> <htype>vrt_hst</htype> <ip_address>192.0.2.123</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>c4u7dwbc2y8</ftp_login> <ftp_password>qweqwe</ftp_password> <ip_address>192.0.2.54</ip_address> </vrt_hst> </hosting> </add> </domain> </packet>

426

Supported Operations

Creating multiple domain accounts

To create two domain accounts with a single packet, include two different add nodes:
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>example.com</name> <htype>vrt_hst</htype> <ip_address>192.0.2.123</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>c4u7dwbc2y8</ftp_login> <ftp_password>qweqwe</ftp_password> <ip_address>192.0.2.54</ip_address> </vrt_hst> </hosting> </add> <add> <gen_setup> <name>sample.com</name> <ip_address>192.0.2.124</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>c4u7dwbc2y8</ftp_login> <ftp_password>qweqwe</ftp_password> <ip_address>192.0.2.54</ip_address> </vrt_hst> </hosting> </add> </domain> </packet>

Supported Operations

427

Using a domain template The following sample packet creates a domain account based on the domain template.
<packet version=1.4.2.0> <domain> <add> <gen_setup> <name>example.com</name> <htype>vrt_hst</htype> <ip_address>192.0.2.123</ip_address> <status>0</status> </gen_setup> <hosting> <vrt_hst> <ftp_login>c4u7dwbc2y8</ftp_login> <ftp_password>qweqwe</ftp_password> <ip_address>192.0.2.54</ip_address> </vrt_hst> </hosting> <template-name>base_template</template-name> </add> </domain> </packet>

Note: To see the sample packets that set optional domain settings (hosting settings, limits, preferences, and others), refer to the related section in the Domain Settings (on page 383)section.

Response Packet Structure


The add node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested add operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the add operation. Data type: string. Allowed values: ok | error.

428

Supported Operations

The errcode node is optional. Is used to return the error code when the add operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the add operation fails. Data type: string. The id node is optional. It is required if the add operation succeeds. Returns the unique identifier of the domain account just added to Plesk. Data type: integer.

Response Samples
A positive response got from the server after adding a new domain account looks as follows:
<packet version=1.4.2.0> <domain> <add> <result> <status>ok</status> <id>2435</id> </result> </add> </domain> </packet>

A negative response can look as follows (you can get a different error code depending on what caused the failure):
<packet version=1.4.2.0> <domain> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </add> </domain> </packet>

Supported Operations

429

Getting Information About Domain Accounts


Plesk Administrator can request any information about any domain account registered in Plesk database. Plesk resellers can request information on their own domains and their clients' domains. In turn, Plesk clients can get information on their own domain accounts only. This information is as follows: general information (domain name and ID, hosting type, the owner) hosting settings performance settings limits on use of Plesk resources domain preferences domain administrator settings disk usage a domain template used to create a domain

Plesk user can get all information at once or specify certain kinds of information (e.g., only hosting settings). The information can be selected for a certain domain, for a group of domains, for all domains belonging to a certain Plesk user (or several), or for all domains registered in Plesk. To request the information about domains, use a request XML packet with the get operation. Note: If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions, and you request info on domain accounts owned by a reseller using get, Plesk will return info on only reseller's personal domain accounts, excluding those owned by the reseller's clients. To retrieve info on domain accounts owned by Plesk Administrator, specify artificial client account login name in the filtering rule. If you request info on all domain accounts, the info on all domain accounts (including the accounts owned by Plesk Administrator) will be returned.

In this section:
Request Packet Structure.................................................................................. 430 Request Samples .............................................................................................. 431 Response Packet Structure ............................................................................... 435 Response Samples ........................................................................................... 437

430

Supported Operations

Request Packet Structure


A request XML packet getting information about the specified domain(s) includes the get operation node:
<packet version=1.4.2.0> <domain> <get> </get> </domain> </packet>

The get node does not have a separate data type, it is nested within the DomainTypeRequest complex type (domain_input.xsd). The get node has the following graphics representation:

The filter node is required. It specifies domains whose information will be got from Plesk database. Data type: DomainFilterType (domain_input.xsd). To see the structure of this node, proceed to topic Filtering Issues (see page 379). The dataset node is required. It specifies what type of information about the specified domains is requested. Data type: domainDatasetType (plesk_domain.xsd). The gen_info node is optional. It is used to request general information about the specified domains. Data type: none. The hosting node is optional. It is used to request hosting settings of the specified domains. Data type: none. The limits node is optional. It is used to request the limits on Plesk resources set for the specified domains. Data type: none. The stat node is optional. It is used to request statistics settings of the specified domains. Data type: none. The prefs node is optional. It is used to request preferences set for the specified domains. Data type: none.

Supported Operations

431

The user node is optional. It is used to request domain administrator settings. Data type: none. The disk_usage node is optional. It is used to request the disk usage information for the specified domains. Data type: none. The performance node is optional. It is used to request performance settings set for the specified domains. Data type: none. This node is supported in API RPC 1.4.0.0 and higher.

Request Samples
If you work in the Plesk 9 backward compatibility mode, the following packet will request info on all domain accounts owned by Plesk Administrator:
<packet version=1.5.2.0> <domain> <get> <filter> <client_login>admin</client_login> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

Getting multiple domains under Plesk Administrator Multiple domains can be specified within one filter either by id, or by domain-name. The following packet is invalid as it uses both id and domain-name nodes within one filter:
<packet version=1.6.0.0> <domain> <get> <filter> <id>123</id> <id>124</id> <domain-name>example.com</domain-name> <domain-name>sample.net</domain-name> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

432

Supported Operations

To specify some domains by id and others by domain-name, use different <get> sections:
<packet version=1.6.0.0> <domain> <get> <filter> <id>123</id> <id>124</id> </filter> <dataset> <hosting/> </dataset> </get> <get> <filter> <domain-name>example.com</domain-name> <domain-name>sample.net</domain-name> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

To get the information about all domains registered in Plesk, the following packet can be used:
<packet version=1.4.2.0> <domain> <get> <filter/> <dataset> <hosting/> </dataset> </get> </domain> </packet>

Supported Operations

433

To get all domains of a certain Plesk user, use group filtering (see the Filtering Issues (see page 379) section for details). Plesk users whose domains are requested can be specified within one filter either by owner-id or by owner-login.
<packet version=1.6.0.0> <domain> <get> <filter> <owner-login>JDoe</owner-login> <owner-login>RRoe</ownerlogin> </filter> <dataset> <hosting/> </dataset> </get> <get> <filter> <owner-id>1342</owner-id> <owner-id>1452</owner-id> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

You cannot specify Plesk users by login and by id in one filter. Use different filters (and <get> nodes) instead. Getting multiple domains under Plesk reseller Plesk resellers can manage their own domains and domains belong to their clients. To get information on all domains of his clients, specify request packet as follows:
<packet version=1.6.0.0> <domain> <get> <filter> <owner-login>JDoe</owner-login> </filter> <dataset> <hosting/> </dataset> </get> <get> <filter> <owner-id>1342</owner-id> </filter> <dataset> <hosting/> </dataset> </get> </domain> </packet>

434

Supported Operations

To retrieve information on all domains belonging to the calling Plesk reseller, specify request packet as follows:
<packet version=1.6.0.0> <domain> <get> <filter/> <dataset> <hosting/> </dataset> </get> </domain> </packet>

Getting multiple domains under Plesk client Plesk clients can manage their own domain accounts only. They cannot apply group filtering using nodes owner-id and owner-login. In all other respects, the request packets shown above can be used by Plesk clients too. One more exception is: the following packet gets the information about all domains belonging to the calling Plesk client.
<packet version=1.4.2.0> <domain> <get> <filter/> <dataset> <hosting/> </dataset> </get> </domain> </packet>

Getting different types of information To get the whole set of information about Plesk user domains, use the following packet:
<packet version=1.6.0.0> <domain> <get> <filter/> <owner-login>RRoe</owner-login> </filter> <dataset/> </get> </domain> </packet>

Supported Operations

435

To fetch a particular kind of data (e.g. hosting settings, limits, and statistics settings), add certain child elements to in the dataset section as follows:
<packet version=1.4.2.0> <domain> <get> <filter> <id>123</id> </filter> <dataset> <hosting/> <limits/> <stat/> </dataset> </get> </domain> </packet>

Response Packet Structure


The get node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested get operation. It can be missing if some error occurs before the validation starts. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Ii is used to return the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the get operation fails. Data type: string.

436

Supported Operations

The filter-id node is optional. Is supported by API RPC 1.4.2.0 and later. If supported, it is always present and used to return the parameter by which the domain was filtered by in the request packet. Data type: anySimple. The id node is optional. The node is always missing if the request packet fails before the validation on the server side. If present, it returns the identifier of the domain whose settings are requested. Data type: integer. The data node is optional. It is used to return a collection of requested domain settings if the get operation succeeds. Data type: none.

The data node of the response get packet is structured as follows:

The gen_info node is optional. If specified in the request packet, it returns a collection of general domain settings. Data type: domainGenInfoType (plesk_domain.xsd). See the General Account Information (see page 387) topic for details. The hosting node is optional. If specified in the request packet, it returns hosting settings of the specified domain. Data type: domainHostingAgentGet (plesk_domain.xsd). See the Hosting Settings (see page 397)topic for details. The limits node is optional. If specified in the request packet, it returns a collection of limits set for the specified domains. Data type: domainLimits (plesk_domain.xsd). See the Limits (see page 397)topic for details. The stat node is optional. If specified in the request packet, it returns a collection of statistics settings set for the specified domain(s). Data type: domainStat (plesk_domain.xsd). See the Statistics Settings (see page 418) topic for details. The prefs node is optional. If specified in the request packet, it returns a collection of preferences set for the specified domains. Data type: domainPrefs (plesk_domain.xsd). See the Domain Preferences (see page 420) topic for details. The user node is optional. If specified in the request packet, it returns a collection of domain administrator settings. Data type: domainUserGet (plesk_domain.xsd). See the Domain Administrator Settings (see page 394)topic for details. The disk_usage node is optional. If specified in the request packet, it returns a collection of hard disk limits set for the specified domains. Data type: none. See the Disk Usage Settings (see page 415)topic for details.

Supported Operations

437

The performance node is optional. If specified in the request packet, it returns a collection of performance settings set for the specified domains. Data type: DomainPerformanceType (plesk_domain.xsd). See the Performance Settings (see page 421) topic for details. This node is supported in API RPC 1.4.0.0 and higher.

Response Samples
A positive response received from the server contains the information for each requested domain in a separate result block. The following response packet returns domain preferences for two specified domains:
<packet version=1.4.2.0> <domain> <get> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> <data> <prefs> <www>true</www> </prefs> </data> </result> <result> <status>ok</status> <id>2567</id> <data> <prefs> <www>true</www> <stat_ttl>6</stat_ttl> </prefs> </data> </result> </get> </domain> </packet>

438

Supported Operations <packet version=1.4.1.2> <domain> <get> <result> <status>ok</status> <id>2435</id> <data> <prefs> <www>true</www> </prefs> </data> </result> <result> <status>ok</status> <id>2567</id> <data> <prefs> <www>true</www> <stat_ttl>6</stat_ttl> </prefs> </data> </result> </get> </domain> </packet>

Notice the difference in these identical packets sent using different versions of API RPC: versions 1.4.1.2 and earlier return the domain identifier in its id node; versions 1.4.2.0 and later return the filtering parameter (the filter-id node) and the domain identifier (the id node). These two nodes can coincide if the domain was filtered by domain_id.

If you need an example of a particular setting returned in the response get packet, proceed to a related topic of the Domain Settings (on page 383) section. If the request get packet asks for a certain kind of settings, but the specified domain is missing these settings in the database, the response get packet will return the requested node (e.g. prefs) empty:
<packet version=1.4.2.0> <domain> <get> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> <data> <prefs/> </data> </result> </get> </domain> </packet>

Supported Operations <packet version=1.4.1.2> <domain> <get> <result> <status>ok</status> <id>2435</id> <data> <prefs/> </data> </result> </get> </domain></packet>

439

If the get operation fails, a negative response can look as follows (you can get a different error code depending on the cause of the failure):
<packet version=1.4.2.0> <domain> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> <filter-id>1234</filter-id> </result> </get> </domain> </packet> <packet version=1.4.1.2> <domain> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> </get> </domain> </packet>

The left packet is sent via API RPC 1.4.1.2 and does not return the domain identifier. The right packet is sent using API RPC 1.4.2.0, it indicates the filtering parameter (this time the domain ID) in the filter-id node.

440

Supported Operations

Deleting Domain Accounts


Domain accounts can be deleted individually or in bulk. Plesk Administrator can delete any domain account available in Plesk, while Plesk clients can delete their own domain accounts only. Domain accounts are deleted by sending a del request packet to Plesk server.

In this section:
Request Packet Structure.................................................................................. 440 Request Samples .............................................................................................. 441 Response Packet Structure ............................................................................... 442 Response Samples ........................................................................................... 443

Request Packet Structure


A request XML packet that deletes domain accounts should include the del operation node:
<packet version=1.4.2.0> <domain> <del> </del> </domain> </packet>

The del node does not have a separate type, it is nested within the DomainTypeRequest complex type (domain_input.xsd). The del node has the following graphics representation:

The filter node is required. It indicates domains to be deleted. Data type: DomainFilterType (domain_input.xsd). To see the structure of this node, proceed to topic Filtering Issues (see page 379).

Supported Operations

441

Request Samples
Deleting multiple domain accounts under Plesk Administrator or under Plesk reseller Plesk Administrator can remove any domain in Plesk server, Plesk reseller can remove any domain belongs to his client. To delete multiple domains, the request packet should filter them either by id, or by domain-name. The following packet is invalid as it uses both id and domain-name nodes within one filter:
<packet version=1.6.0.0> <domain> <del> <filter> <id>123</id> <id>124</id> <domain-name>example.com</domain-name> <domain-name>sample.net</domain-name> </filter> </del> </domain> </packet>

To filter some domains by id and others by domain-name, use different <del> sections:
<packet version=1.6.0.0> <domain> <del> <filter> <id>123</id> <id>124</id> </filter> </del> <del> <filter> <domain-name>example.com</domain-name> <domain-name>sample.net</domain-name> </filter> </del> </domain> </packet>

To delete all domains registered in Plesk, the following packet can be used:
<packet version=1.4.2.0> <domain> <del> <filter/> </del> </domain> </packet>

442

Supported Operations

To delete all domains of a certain Plesk user, use group filtering (see the Filtering Issues (see page 379) section for details). Plesk users whose domains are deleted can be specified within one filter either by owner-id or by owner-login.
<packet version=1.6.0.0> <domain> <del> <filter> <owner-login>example.com</owner-login> <owner-login>sample.net</owner-login> </filter> </del> <del> <filter> <owner-id>1342</owner-id> <owner-id>1452</owner-id> </filter> </del> </domain> </packet>

You cannot specify Plesk users by login and by id in one filter. Use different filtering rules instead.

Response Packet Structure


The del node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested del operation. It can be missing if some error occurs before the validation starts. Data type: resultFilterType (common.xsd). The status node is required. It returns the execution status of the del operation. Data type: string. Allowed values: ok | error.

Supported Operations

443

The errcode node is optional. It is used to return an error code when the del operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the del operation fails. Data type: string. The filter-id node is optional. Is supported by API RPC 1.4.2.0 and later. If supported, it is always present and used to return the parameter by which the domain was filtered by in the request packet. Data type: anySimple. The id node is optional. It is missing if the request packet fails before the validation on the server side. If present, this node identifies the deleted domain. Data type: integer.

Response Samples
A positive response got from the server after deleting the specified domains (e.g. with id = 2435 and id = 2446) looks as follows:
<packet version=1.4.1.2> <domain> <del> <result> <status>ok</status> <id>2435</id> </result> <result> <status>ok</status> <id>2446</id> </result> </del> </domain> </packet> <packet version=1.4.2.0> <domain> <del> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> </result> <result> <status>ok</status> <filter-id>2446</filter-id> <id>2446</id> </result> </del> </domain> </packet>

Notice the difference in these identical packets sent using different versions of API RPC: versions 1.4.1.2 and earlier return the domain identifier in its id node; versions 1.4.2.0 and later return the filtering parameter (the filter-id node) and the domain identifier (the id node). These two nodes can coincide if the domain was filtered by domain_id.

444

Supported Operations

A negative response can look as follows:

<packet version=1.4.1.2> <domain> <del> <result> <status>ok</status> <id>2435</id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> </del> </domain> </packet>

<packet version=1.4.2.0> <domain> <del> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> <filter-id>2446</filter-id> </result> </del> </domain> </packet>

The left packet is sent via API RPC 1.4.1.2 and does not return the domain identifier. The right packet is sent using API RPC 1.4.2.0, it indicates the filtering parameter (this time the domain id) in the filter-id node.

Supported Operations

445

Setting Domain Parameters


Plesk Administrator can set any setting for any domain account registered in Plesk database. Plesk clients are allowed to manage their own domains only. The settings are as follows: General domain account information (see page 383) Hosting settings (see page 397) Performance settings (see page 421) Limits (see page 397) on use of Plesk resources Disk usage settings (see page 415) Domain preferences (see page 420) Domain administrator settings (see page 392)

Plesk Administrator can change the base domain settings - the domain name, the IP address, and the domain owner (Plesk client). A collection of domain settings can be applied to one or several domain accounts at a time. Plesk Administrator can set domain settings for all domains belonging to a certain Plesk client, or for several clients. Domain settings are set by sending a request set packet to Plesk server.

In this section:
Request Packet Structure.................................................................................. 446 Request Samples .............................................................................................. 447 Response Packet Structure ............................................................................... 450 Response Samples ........................................................................................... 451

446

Supported Operations

Request Packet Structure


A request XML packet that sets a collection of domain settings should include the set operation node:
<packet version=1.4.2.0> <domain> <set> </set> </domain> </packet>

The set node does not have a separate type, it is nested within the DomainTypeRequest complex type (domain_input.xsd). The set node has the following graphics representation:

The filter node is required. It indicates domains to be updated with the specified information. Data type: DomainFilterType (domain_input.xsd). To see the structure of this node, proceed to topic Filtering Issues (see page 379). The values node is required. It contains a collection of settings that will be set for the filtered domains. Data type: none. The gen_setup node is optional. It specifies a collection of general domain settings that will be set for the filtered domains. Data type: SetGenSetupType (plesk_domain.xsd). To see the structure of this node, proceed to topic General Account Information (see page 390). The limits node is optional. It specifies the limits on use of Plesk resources for the filtered domains. Data type: domainLimits (plesk_domain.xsd). To see the structure of this node, proceed to the Limits (see page 397)topic. The prefs node is optional. It specifies a collection of preferences for the filtered domains. Data type: domainPrefs (plesk_domain.xsd). To see the structure of this node, proceed to topic Domain Preferences (see page 420). The hosing node is optional. It specifies hosting settings for the filtered domains. Data type: domainHostingAgentSet (plesk_domain.xsd). To see the structure of this node, proceed to topic Hosting Settings (see page 397).

Supported Operations

447

The user node is optional. It specifies domain administrator settings. Data type: domainUserSet (plesk_domain.xsd). To see the structure of this node, proceed to topic Domain Administrator Settings (see page 392). The disk_usage node is optional. It specifies the amount of disk space allotted for email boxes and mailing lists on the filtered domain(s). Data type: none. To see the structure of this node, proceed to topic Disk Space Usage Settings (see page 415). The performance node is optional. It specifies a collection of performance settings for the filtered domains. Data type: DomainPerformanceType (plesk_domain.xsd). This node is actual beginning with API RPC 1.4.1.0 only. To see the structure of this node, proceed to topic Performance Settings (see page 421).

Request Samples
Setting data for multiple domains under Plesk Administrator The following packet changes GUIDs of all domains. It is valid only in API RPC 1.5.2.0 and later versions.
<packet version=1.5.2.0> <domain> <set> <filter/> <values> <gen_setup> <guid/> </gen_setup> </values> </set> </domain> </packet>

Multiple domains can be specified within one filter either by id, or by domain_name. The following packet is invalid as it uses both id and domain_name nodes within one filter:
<packet version=1.6.0.0> <domain> <set> <filter> <id>123</id> <id>124</id> <domain-name>techservice.co.uk</domain-name> <domain-name>techknowledge.co.uk</domain-name> </filter> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> </domain> </packet>

448

Supported Operations

To specify some domains by id and others by domain_name, use different set nodes:
<packet version=1.4.2.0> <domain> <set> <filter> <id>123</id> <id>124</id> </filter> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> <set> <filter> <domain_name>techservice.co.uk</domain_name> <domain_name>techknowledge.co.uk</domain_name> </filter> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> </domain> </packet>

To set the same settings for all domains registered in Plesk, the following packet can be used:
<packet version=1.4.2.0> <domain> <set> <filter/> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> </domain> </packet>

Supported Operations

449

To set the same settings for all domains of a certain Plesk client, use group filtering (see topic Filtering Issues (see page 379) for details). Plesk clients whose domains are requested can be specified within one filter either by client_id or by client_login.
<packet version=1.6.0.0> <domain> <set> <filter> <owner-login>technolux</owner-login> <owner-login>technologic</owner-login> </filter> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> <set> <filter> <owner-id>1342</owner-id> <owner-id>1452</owner-id> </filter> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> </domain> </packet>

You cannot specify clients by login and by ID in one filter. Use different filters (and set operations) instead. Setting data for multiple domains under Plesk client Plesk clients can manage their own domain accounts only. Thus, they cannot apply group filtering using nodes owner-id and owner-login. One more exception is: the following packet sets the data for all domains belonging to the calling Plesk client.
<packet version=1.4.2.0> <domain> <set> <filter/> <values> <performance> <bandwidth>-1</bandwidth> </performance> </values> </set> </domain> </packet>

450

Supported Operations

Since the set packet means the update of domain settings in Plesk database, the values node cannot be left empty. The following packet will cause the error:
<packet version=1.4.2.0> <domain> <set> <filter> <id>123</id> </filter> <values/> </set> </domain> </packet>

The values node can specify some or all kinds of settings. To see the sample packet for a certain setting, proceed to the relevant sub-topic of Domain Settings (on page 383).

Response Packet Structure


The set node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested set operation. It can be missing if some error occurs before the validation starts. Data type: resultFilterType (common.xsd). The status node is required. It returns the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code if the set operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the set operation fails. Data type: string. The filter-id node is optional. It is supported by API RPC 1.4.2.0 and later. If supported, it is always present and used to return the parameter by which the domain was filtered by in the request packet. Data type: anySimple.

Supported Operations

451

The id node is optional. It is missing if the request packet fails before the validation on the server side. If present, this node identifies the domain whose settings are updated. Data type: integer.

Response Samples
A positive response got from the server after updating the specified domains (e.g. with ID 2435 and ID 2446) looks as follows:
<packet version=1.4.1.2> <domain> <set> <result> <status>ok</status> <id>2435</id> </result> <result> <status>ok</status> <id>2446</id> </result> </set> </domain> </packet> <packet version=1.4.2.0> <domain> <set> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> </result> <result> <status>ok</status> <filter-id>2446</filter-id> <id>2446</id> </result> </set> </domain> </packet>

Notice the difference in these identical packets sent using different versions of API RPC: versions 1.4.1.2 and earlier return the domain identifier in its id node; versions 1.4.2.0 and later return the filtering parameter (the filter-id node) and the domain identifier (the id node). These two nodes can coincide if the domain was filtered by domain_id.

452

Supported Operations

A negative response can look as follows:


<packet version=1.4.1.2> <domain> <set> <result> <status>ok</status> <id>2435</id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> </set> </domain> </packet> <packet version=1.4.2.0> <domain> <set> <result> <status>ok</status> <filter-id>2435</filter-id> <id>2435</id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> <filter-id>2446</filter-id> </result> </set> </domain> </packet>

The left packet is sent via API RPC 1.4.1.2 and does not return the domain identifier. The right packet is sent using API RPC 1.4.2.0, it indicates the filtering parameter (this time the domain ID) in the filter-id node.

Supported Operations

453

Getting the Domain Buttons List


Each domain account has its own page in Plesk GUI (Domains -> select any domain from the list). This page displays a collection of buttons. This list of buttons can be got from Plesk database for the specified domain. To do so, you need to send the cform_buttons_list request packet to Plesk server.

In this section:
Request Packet Structure.................................................................................. 453 Request Samples .............................................................................................. 454 Response Packet Structure ............................................................................... 455 Response Samples ........................................................................................... 458

Request Packet Structure


A request XML packet getting the list of domain buttons includes the cform_buttons_list operation node:
<packet version=1.4.2.0> <domain> <cform_buttons_list> </cform_buttons_list> </domain> </packet>

The cform_buttons_list node does not have a separate data type, it is nested within the DomainTypeRequest complex type (domain_input.xsd). The cform_buttons_list node has the following graphics representation:

The filter node is required. It indicates domains whose buttons are requested. Data type: DomainFilterType (domain_input.xsd). To see the structure of this node, proceed to topic Filtering Issues (see page 379).

454

Supported Operations

Request Samples
Getting buttons under Plesk Administrator To get buttons for multiple domains, the cform_buttons_list request packet should filter them in the filter node either by id, or by domain_name. The following packet is invalid as it uses both id and domain_name nodes within one filter:
<packet version=1.4.2.0> <domain> <cform_buttons_list> <filter> <id>123</id> <id>124</id> <domain_name>techservice.co.uk</domain_name> <domain_name>techknowledge.co.uk</domain_name> </filter> </cform_buttons_list> </domain> </packet>

To filter some domains by id and others by domain_name, use different cform_buttons_list nodes:
<packet version=1.4.2.0> <domain> <cform_buttons_list> <filter> <id>123</id> <id>124</id> </filter> </cform_buttons_list> <cform_buttons_list> <filter> <domain_name>techservice.co.uk</domain_name> <domain_name>techknowledge.co.uk</domain_name> </filter> </cform_buttons_list> </domain> </packet>

To get buttons of all domains registered in Plesk, the following packet can be used:
<packet version=1.4.2.0> <domain> <cform_buttons_list> <filter/> </cform_buttons_list> </domain> </packet>

Supported Operations

455

To get buttons of all domains belonging to a certain Plesk client, use group filtering (see topic Filtering Issues (see page 379) for details). Plesk clients whose domains are filtered can be specified within one filter either by client_id or by client_login.
<packet version=1.4.2.0> <domain> <cform_buttons_list> <filter> <client_login>technolux</client_login> <client_login>technologic</client_login> </filter> </cform_buttons_list> <cform_buttons_list> <filter> <client_id>1342</client_id> <client_id>1452</client_id> </filter> </cform_buttons_list> </domain> </packet>

You cannot specify clients by login and by ID in one filter. Use different filters (and cform_buttons_list nodes) instead.

Response Packet Structure


The cform_buttons_list node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested cform_buttons_list operation. It can be missing if some error occurs before the validation starts. Data type: resultFilterType (common.xsd).

456

Supported Operations

The status node is required. It returns the execution status of the cform_buttons_list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return an error code if the cform_buttons_list operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the cform_buttons_list operation fails. Data type: string. The filter-id node is optional. It is supported by API RPC 1.4.2.0 and later. If supported, it is always present and used to return the parameter by which the domain was filtered by in the request packet. Data type: anySimple. The id node is optional. Returns the identifier of the domain whose buttons are requested. It is missing if the request packet fails before the validation on the server side. Data type: integer. The button node is optional. It returns a collection of parameters that describe the button (see the details below). It is missing if the request packet fails before the validation on the server side. Data type: buttonDataType (plesk_common.xsd).

Buttons are described by complex type buttonDataType (plesk_common.xsd) as follows:

The code node is required. It returns the identifier of the button. Data type: string.

Supported Operations

457

The type node is required. It specifies the button type. Data type: string. Allowed values: link_button (a typical link that references some URL) | comm_button (a typical button whose click event calls a related event handler). The name node is required. It contains the localized button name displayed in a home page. Data type: string. The name_id node is required. It specifies the localization key associated with the button. Data type: string. The group_name node is required. It returns the localized name of the group containing the button. Data type: string. The group_name_id node is required. It specifies the localization key of the group name. Data type: string. The href node is required. It returns the URL referenced by the button. Data type: string. The js_onclick node is optional. It returns the JavaScript code executed at the button click. Data type: text (string, white spaces are allowed). The enabled node is required. It indicates whether the button in enabled. If true, the button is active and can be used. Data type: Boolean. The new_window node is optional. It indicates whether a new window should be opened in the browser when the button is clicked. Data type: Boolean. The tabindex node is optional. It returns the buttons tabulation index. Data type: integer. Default value: 0. The conhelp_id node is optional. It specifies the localization key of the context help message associated with the button. Data type: string. The conhelp node is optional. It returns a context help message displayed in the HELP section of the Plesk navigation pane when pointing at the button with a mouse. Data type: text (string, white spaces are allowed). The icon_url node is optional. It specifies the location of the buttons icon. Data type: string.

458

Supported Operations

Response Samples
A positive response with a single button displayed for the specified domain (ID 1324) looks as follows:
<packet version=1.4.1.2> <domain> <cform_buttons_list> <result> <status>ok</status> <id>1324</id> <button> <code>EDIT_BUTTON</code> <type>link_button</type> <name>Edit</name> <name_id>edit</name_id> <group_name>Tools</group_name> <group_name_id>__tools</group_name_id> <href>/domains/d_ed.php3</href> <enabled>true</enabled> <new_window>false</new_window> </button> </result> </cform_buttons_list> </domain> </packet> <packet version=1.4.2.0> <domain> <cform_buttons_list> <result> <status>ok</status> <filter-id>1324</filter-id> <id>1324</id> <button> <code>EDIT_BUTTON</code> <type>link_button</type> <name>Edit</name> <name_id>edit</name_id> <group_name>Tools</group_name> <group_name_id>__tools</group_name_id> <href>/domains/d_ed.php3</href> <enabled>true</enabled> <new_window>false</new_window> </button> </result> </cform_buttons_list> </domain> </packet>

Notice the difference in these identical packets sent using different versions of API RPC: versions 1.4.1.2 and earlier return the domain identifier in its id node;

Supported Operations

459

versions 1.4.2.0 and later return the filtering parameter (the filter-id node) and the domain identifier (the id node). These two nodes can coincide if the domain was filtered by domain_id.

If the operation fails, a negative response can look as follows:


<packet version=1.4.1.2> <domain> <cform_buttons_list> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1324</id> </result> </cform_buttons_list> </domain> </packet> <packet version=1.4.2.0> <domain> <cform_buttons_list> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <filter-id>1324</filter-id> <id>1324</id> </result> </cform_buttons_list> </domain> </packet>

Getting Traffic Usage Information


The get_traffic is used to retrieve information about the traffic spent by a domain between two dates. The resulting information got for each domain lists all days between the specified dates and shows the daily traffic spent by the domain during this day.

In this section:
Request Packet Structure.................................................................................. 460 Request Samples .............................................................................................. 460 Response Packet Structure ............................................................................... 463 Response Samples ........................................................................................... 465

460

Supported Operations

Request Packet Structure


A request XML packet getting traffic information for the specified domains includes the get_traffic operation node:
<packet version=1.4.2.0> <domain> <get_traffic> </get_traffic> </domain> </packet>

The get_traffic node does not have a separate data type, it is nested within the DomainTypeRequest complex type (domain_input.xsd). The get_traffic node has the following graphics representation:

The filter node is required. It specifies domains whose traffic information will be got from Plesk database. Data type: DomainFilterType (domain_input.xsd). To see the structure of this node, proceed to topic Filtering Issues (see page 379). The since_date node is optional. It specifies the starting date of the period. If the packet is missing this node, the analyzed days will not be limited below. Data type: date. Format: YYYY-MM-DD. The to_date node is optional. It specifies the end date of the period. If the packet is missing this element, the period will be limited by the date of the request execution. Data type: date. Format: YYYY-MM-DD.

If the packet is missing both nodes since_date and to_date, the response packet will show the traffic of the specified domain day by day since its creation and up to the date of the request execution.

Supported Operations

461

Request Samples
Getting traffic info under Plesk Administrator Plesk Administrator can get traffic information for all domains available in Plesk. Domains are specified within one filter either by id, or by domain_name. The following packet is invalid as it uses both id and domain_name nodes within one filter:
<packet version=1.4.2.0> <domain> <get_traffic> <filter> <id>1234</id> <id>1235</id> <domain_name>technolux.co.uk</domain_name> <domain_name>softlux.com</domain_name> </filter> <since_date>2006-10-01</since_date> </get_traffic> </domain> </packet>

A valid packet will use two different filter nodes (in two different get_traffic operations):
<packet version=1.4.2.0> <domain> <get_traffic> <filter> <id>1234</id> <id>1235</id> </filter> <since_date>2006-10-01</since_date> </get_traffic> <get_traffic> <filter> <domain_name>technolux.co.uk</domain_name> <domain_name>softlux.com</domain_name> </filter> <since_date>2006-10-01</since_date> </get_traffic> </domain> </packet>

462

Supported Operations

To get traffic information for all domains belonging to a certain Plesk client, use group filtering (see topic Filtering Issues (see page 379) for details). Plesk clients whose domains are filtered can be specified within one filter either by client_id or by client_login.
<packet version=1.4.2.0> <domain> <get_traffic> <filter> <client_login>technolux</client_login> <client_login>technologic</client_login> </filter> <since_date>2006-10-01</since_date> </get_traffic> <get_traffic> <filter> <client_id>1342</client_id> <client_id>1452</client_id> </filter> <since_date>2006-10-01</since_date> </get_traffic> </domain> </packet>

You cannot specify clients by login and by ID in one filter. Use different filters (and cform_buttons_list nodes) instead. To get traffic information for all domains available in Plesk, send the following packet:
<packet version=1.4.2.0> <domain> <get_traffic> <filter/> <since_date>2006-10-01</since_date> </get_traffic> </domain> </packet>

Supported Operations

463

Response Packet Structure


The get_traffic node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested get_traffic operation. It can be missing if some error occurs before the validation starts. Data type: resultFilterType (common.xsd). The status node is required. It returns the execution status of the get_traffic operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return an error code if the get_traffic operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the get_traffic operation fails. Data type: string. The filter-id node is optional. Is supported by API RPC 1.4.2.0 and later. If supported, it is always present and used to return the parameter by which the domain was filtered by in the request packet. Data type: anySimple. The id node is optional. Returns the identifier of the domain whose traffic is requested. It is missing if the request packet fails before the validation on the server side. Data type: integer. The traffic node is optional. It contains a collection of traffic data obtained from Plesk server (see below). Data type: trafficType (plesk_domain.xsd).

The traffic node is defined by type trafficType (plesk_domain.xsd). It is structured as follows:

464

Supported Operations

The date node is required. It specifies the date for which the traffic is shown. Data type: date. Format: YYYY-MM-DD. The http_in node is required. It shows the incoming traffic (in bytes) got via HTTP protocol. Data type: integer. The http_out node is required. It shows the outgoing HTTP traffic (in bytes). Data type: integer. The ftp_in node is required. It shows the incoming traffic (in bytes) got via FTP protocol. Data type: integer. The ftp_out node is required. It shows the outgoing FTP traffic (in bytes). Data type: integer. The smtp_in node is required. It shows the incoming traffic (in bytes) got via SMTP protocol. Data type: integer. The smtp_out node is required. It shows the outgoing SMTP traffic (in bytes). Data type: integer. The pop3_imap_in node is required. It shows the incoming traffic (in bytes) got via POP3 and IMAP protocols. Data type: integer. The pop3_imap_out node is required. It shows the outgoing POP3/IMAP traffic (in bytes). Data type: integer.

Supported Operations

465

Response Samples
A positive response that returns the traffic spent by the specified domains can look as shown below. This packet returns the information about traffic for two dates for two domains.
<packet version=1.4.1.2> <domain> <get_traffic> <result> <status>ok</status> <id>1234</id> <traffic> <date>2005-12-12</date> <http_in>4371212365846</http_in> <http_out>1234111122</http_out> <ftp_in>4121253</ftp_in> <ftp_out>163553</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341156</smtp_out> <pop3_imap_in>1545682</pop3_imap_in> <pop3_imap_out>15434674</pop3_imap_out> </traffic> <traffic> <date>2005-12-13</date> <http_in>4371978643846</http_in> <http_out>1234548722</http_out> <ftp_in>4121153</ftp_in> <ftp_out>123653</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341356</smtp_out> <pop3_imap_in>1511112</pop3_imap_in> <pop3_imap_out>16458674</pop3_imap_out> </traffic> </result> <result> <status>ok</status> <id>1247</id> <traffic> <date>2005-12-12</date> <http_in>4371243251846</http_in> <http_out>1234111122</http_out> <ftp_in>4125453</ftp_in> <ftp_out>123153</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341356</smtp_out> <pop3_imap_in>1543512</pop3_imap_in> <pop3_imap_out>15436374</pop3_imap_out> </traffic> <traffic> <date>2005-12-13</date> <http_in>4371243251846</http_in> <http_out>1234111122</http_out> <ftp_in>4125453</ftp_in> <ftp_out>123153</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341356</smtp_out> <pop3_imap_in>1543512</pop3_imap_in> <pop3_imap_out>15436374</pop3_imap_out>

466

Supported Operations </traffic> </result> </get_traffic> </domain> </packet> <packet version=1.4.2.0> <domain> <get_traffic> <result> <status>ok</status> <filter-id>1234</filter-id> <id>1234</id> <traffic> <date>2005-12-12</date> <http_in>4371212365846</http_in> <http_out>1234111122</http_out> <ftp_in>4121253</ftp_in> <ftp_out>163553</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341156</smtp_out> <pop3_imap_in>1545682</pop3_imap_in> <pop3_imap_out>15434674</pop3_imap_out> </traffic> <traffic> <date>2005-12-13</date> <http_in>4371978643846</http_in> <http_out>1234548722</http_out> <ftp_in>4121153</ftp_in> <ftp_out>123653</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341356</smtp_out> <pop3_imap_in>1511112</pop3_imap_in> <pop3_imap_out>16458674</pop3_imap_out> </traffic> </result> <result> <status>ok</status> <filter-id>1247</filter-id> <id>1247</id> <traffic> <date>2005-12-12</date> <http_in>4371243251846</http_in> <http_out>1234111122</http_out> <ftp_in>4125453</ftp_in> <ftp_out>123153</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341356</smtp_out> <pop3_imap_in>1543512</pop3_imap_in> <pop3_imap_out>15436374</pop3_imap_out> </traffic> <traffic> <date>2005-12-13</date> <http_in>4371243251846</http_in> <http_out>1234111122</http_out> <ftp_in>4125453</ftp_in> <ftp_out>123153</ftp_out> <smtp_in>123535</smpt_in> <smtp_out>341356</smtp_out>

Supported Operations <pop3_imap_in>1543512</pop3_imap_in> <pop3_imap_out>15436374</pop3_imap_out> </traffic> </result> </get_traffic> </domain> </packet>

467

Notice the difference in these identical packets sent using different versions of API RPC: Versions 1.4.1.2 and earlier return the domain identifier in its id node. Versions 1.4.2.0 and later return the filtering parameter (the filter-id node) and the domain identifier (the id node). These two nodes can coincide if the domain was filtered by domain_id.

If the operation fails, a negative response can look as follows:


<packet version=1.4.1.2> <domain> <get_traffic> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1324</id> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1247</id> </result> </get_traffic> </domain> </packet> <packet version=1.4.2.0> <domain> <get_traffic> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <filter-id>1234</filter-id> <id>1324</id> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <filter-id>1247</filter-id> <id>1247</id> </result> </get_traffic></domain></packet>

The right packet is sent using API RPC 1.4.2.0, it indicates the filtering parameter (this time the domain ID) in the filter-id node.

468

Supported Operations

Setting Domain Traffic Settings


If the traffic usage is calculated on a domain by statistics facilities of Plesk, this data is added to Plesk automatically. If this data is gathered using some external statistics means, the set_traffic operation can help add this data to Plesk database.

In this section:
Request Packet Structure.................................................................................. 468 Request Samples .............................................................................................. 469 Response Packet Structure ............................................................................... 470 Response Samples ........................................................................................... 471

Request Packet Structure


A request XML packet that sets traffic data for a certain domain should include the set_traffic operation node:
<packet version=1.4.2.0> <domain> <set_traffic> </set_traffic> </domain> </packet>

The set_traffic node does not have a separate type, it is nested within the DomainTypeRequest complex type (domain_input.xsd). The set_traffic node has the following graphics representation:

The dom_id node is required. It identifies the domain whose traffic settings are set. Data type: integer. The date node is required. It specifies the date for which the traffic data is set. Data type: date. Format: YYYY-MM-DD. The smtp_in node is required. It specifies the incoming traffic (in bytes) got via SMTP protocol. Data type: integer. The smtp_out node is required. It is used to show the outgoing SMTP traffic (in bytes). Data type: integer.

Supported Operations

469

The pop3_imap_in node is required. It specifies the incoming traffic (in bytes) got via POP3 and IMAP protocols. Data type: integer. The pop3_imap_out node is required. It is used to show the outgoing POP3/IMAP traffic (in bytes). Data type: integer.

Request Samples
To set traffic information for the specified domain, use the following packet:
<packet version=1.4.2.0> <domain> <set_traffic> <dom_id>1134</dom_id> <date>2005-12-12</date> <smtp_in>514237124628</smtp_in> <smtp_out>6153462547</smtp_out> <pop3_imap_in>49769379</pop3_imap_in> <pop3_imap_out>7236487263<pop3_imap_out> </set_traffic> </domain> </packet>

To set traffic information for multiple domains in one packet, use multiple <set_traffic> nodes:
<packet version=1.4.2.0> <domain> <set_traffic> <dom_id>1134</dom_id> <date>2005-12-12</date> <smtp_in>127417</smtp_in> <smtp_out>342899</smtp_out> <pop3_imap_in>384769</pop3_imap_in> <pop3_imap_out>37947<pop3_imap_out> </set_traffic> <set_traffic> <dom_id>1135</dom_id> <date>2005-12-12</date> <smtp_in/> <smtp_out/> <pop3_imap_in>7835683295457</pop3_imap_in> <pop3_imap_out>32876583765<pop3_imap_out> </set_traffic> </domain> </packet>

470

Supported Operations

Response Packet Structure


The set_traffic node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested set_traffic operation. It can be missing if some error occurs before the validation starts. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the set_traffic operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return an error code when the set_traffic operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the set_traffic operation fails. Data type: string. The id node is optional. Returns the identifier of the domain whose traffic is set. It is missing if the request packet fails before the validation on the server side. Data type: integer.

Supported Operations

471

Response Samples
After the traffic data is put to Plesk database, a positive response sent back by Plesk server looks as follows:
<packet version=1.4.2.0> <domain> <set_traffic> <result> <status>ok</status> <id>1234</id> </result> </set_traffic> </domain> </packet>

If the request packet sets traffic data for multiple domains, the response packet will look as follows:
<packet version=1.4.2.0> <domain> <set_traffic> <result> <status>ok</status> <id>1234</id> </result> </set_traffic> <set_traffic> <result> <status>ok</status> <id>1247</id> </result> </set_traffic> </domain> </packet>

The packet will return the result for every filtered domain within a separate set_traffic node. If the operation fails, a negative response can look as follows:
<packet version=1.4.2.0> <domain> <set_traffic> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>1324</id> </result> </set_traffic> </domain> </packet>

472

Supported Operations

Retrieving Descriptor of Limits


Use the get-limit-descriptor operation to retrieve descriptor of domain limits. For details on descriptors, refer to the Representation of Object Descriptor (on page 47) section. For details on limits of a domain, refer to the Limits (on page 397) section.

In this section:
Request Packet Structure.................................................................................. 472 Request Samples .............................................................................................. 472 Response Packet Structure ............................................................................... 474 Response Samples ........................................................................................... 475

Request Packet Structure


A request XML packet retrieving domain limits descriptors includes the get-permitdescriptor operation node:
<packet version=1.5.0.0> <domain> <get-limit-descriptor> </get-limit-descriptor> </domain> </packet>

You can retrieve limits descriptor for the specified domain (or multiple domains specified by client ID or login name), or the server-level domain limits descriptor. The get-limit-descriptor node has the following graphical representation:

The filter node is required. It specifies a filtering rule. For info on filters, refer to the Filters of Descriptors (on page 47) section. Data type: domainFilterType (domain_input.xsd).

Request Samples
The request packet retrieving limits descriptor for the domain with ID 5 looks as follows:
<packet version ="1.5.0.0"> <domain> <get-limit-descriptor> <filter> <id>5</id> </filter> </get-limit-descriptor> </domain> </packet>

Supported Operations

473

The request packet retrieving limits descriptor for MyDomain.com and MySample.com domains looks as follows:
<packet version ="1.5.0.0"> <domain> <get-limit-descriptor> <filter> <domain_name>5</domain_name> <domain_name>7</domain_name> </filter> </get-limit-descriptor> </domain> </packet>

The request packet retrieving limits descriptor for domains of the client specified by ID 3 looks as follows:
<packet version ="1.5.0.0"> <domain> <get-limit-descriptor> <filter> <client_id>3</client_id> </filter> </get-limit-descriptor> </domain> </packet>

474

Supported Operations

The request packet retrieving the server-level descriptor of domain limits looks as follows:
<packet version ="1.5.0.0"> <client> <get-limit-descriptor> <filter/> </get-limit-descriptor> </client> </packet>

Response Packet Structure


The get-limit-descriptor node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (plesk_common.xsd). The status node is required. It specifies the execution status of the get-limit-descriptor operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get-limitdescriptor operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the get-limitdescriptor operation fails. Data type: string. The filter-id node is optional. It is required if the get-limit-descriptor operation succeeds. Returns either domain name, domain ID, client name, or client ID depending on a way of descriptor specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. For info on filters, refer to the Filters of Descriptors (on page 48) section. Data type: anySimple. The id node is optional. It is required if the get-limit-descriptor operation succeeds. Returns the unique identifier of the domain. Data type: integer.

Supported Operations

475

The descriptor node is optional. It specifies the object descriptor. For details, refer to Representation of Object Descriptor (on page 47). Data type: string.

Note: This descriptor contains limits extensions. For details, refer to the Extension of Limits Descriptor (see page 53) section.

Response Samples
A positive response from the server can look as follows:
<packet version="1.5.0.0"> <domain> <get-limit-descriptor> <result> <status>ok</status> <filter-id>MyDomain.com</filter-id> <id>10</id> <descriptor> <property> <name>max_subdom</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_subdom</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_dom_aliases</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_dom_aliases</label> <extension> <shared>false</shared> </extension> </property> <property> <name>disk_space</name> <type>bytes</type> <writable-by>admin</writable-by> <label>limit__disk_space</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_traffic</name> <type>bytes</type> <writable-by>admin</writable-by> <label>limit__max_traffic</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_wu</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_wu</label>

476

Supported Operations <extension> <shared>false</shared> </extension> </property> <property> <name>max_db</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_db</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_box</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_box</label> <extension> <shared>false</shared> </extension> </property> <property> <name>mbox_quota</name> <type>bytes</type> <writable-by>admin</writable-by> <label>limit__mbox_quota</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_redir</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_redir</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_mg</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_mg</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_resp</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_resp</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_maillists</name>

Supported Operations <type>int</type> <writable-by>admin</writable-by> <label>limit__max_maillists</label> <extension> <shared>false</shared> </extension> </property> <property> <name>max_webapps</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_webapps</label> <extension> <shared>false</shared> </extension> </property> <property> <name>expiration</name> <type>date</type> <writable-by>admin</writable-by> <label>limit__expiration</label> <extension> <shared>true</shared> </extension> </property> </descriptor> </result> </get-limit-descriptor> </domain> </packet>

477

If the domain specified in the request packet was not found on the server, the result is as follows:
<packet version="1.5.0.0"> <domain> <get-limit-descriptor> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>MyDomain.com</filter-id> </result> </get-limit-descriptor> </domain> </packet>

478

Supported Operations

Retrieving Descriptor of Permissions


Use the get-permission-descriptor operation to retrieve descriptor of domain administrator's permissions. For details on descriptors, refer to the Representation of Object Descriptor (on page 47) section. For details on permissions of a domain administrator, refer to the Permissions (on page 398) section.

In this section:
Request Packet Structure.................................................................................. 478 Request Samples .............................................................................................. 479 Response Packet Structure ............................................................................... 480 Response Samples ........................................................................................... 480

Request Packet Structure


A request XML packet retrieving descriptor of domain administrator's permissions includes the get-permission-descriptor operation node:
<packet version=1.5.0.0> <domain> <get-limit-descriptor> </get-limit-descriptor> </domain> </packet>

You can retrieve descriptor for the specified domain (or multiple domains specified by client ID or login name) or the server-level descriptor of domain administrator permissions descriptor. The get-permission-descriptor node has the following graphical representation:

The filter node is required. It specifies a filtering rule. For info on filters, refer to the Filters of Descriptors (on page 47) section. Data type: domainFilterType (domain_input.xsd). The id node is optional. It specifies the domain ID. Data type: integer. The client_id node is optional. It specifies the client ID. Data type: integer. The domain_name is optional. It specifies the domain name. Data type: string (UTF-8). The client_login is optional. It specifies the client name. Data type: string.

Note: You can specify multiple id, client_id, domain_name and client_login parameters in one filter node.

Supported Operations

479

Request Samples
The request packet retrieving permissions descriptor for the domain with ID 5 looks as follows:
<packet version ="1.5.0.0"> <domain> <get-permission-descriptor> <filter> <id>5</id> </filter> </get-permission-descriptor> </domain> </packet>

The request packet retrieving permissions descriptor for MyDomain.com and MySample.com domains looks as follows:
<packet version ="1.5.0.0"> <domain> <get-permission-descriptor> <filter> <domain_name>5</domain_name> <domain_name>7</domain_name> </filter> </get-permission-descriptor> </domain> </packet>

The request packet retrieving permissions descriptor for domains of the client specified by ID 3 looks as follows:
<packet version ="1.5.0.0"> <domain> <get-permission-descriptor> <filter> <client_id>3</client_id> </filter> </get-permission-descriptor> </domain> </packet>

The request packet retrieving the server-level descriptor of domain administrator's permissions looks as follows:
<packet version ="1.5.0.0"> <client> <get-limit-descriptor> <filter/> </get-limit-descriptor> </client> </packet>

480

Supported Operations

Response Packet Structure


The get-permission-descriptor node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (plesk_common.xsd). The status node is required. It specifies the execution status of the get-permissiondescriptor operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the getpermission-descriptor operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the getpermission-descriptor operation fails. Data type: string. The filter-id node is optional. It is required if the get-permission-descriptor operation succeeds. Returns either domain name, domain ID, client name, or client ID depending on a way of descriptor's specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. For info on filters, refer to the Filters of Descriptors (on page 48) section. Data type: anySimple. The id node is optional. It is required if the get-permission-descriptor operation succeeds. Returns the unique identifier of the domain. Data type: integer. The descriptor node is optional. It specifies the object descriptor. For details, refer to Representation of Object Descriptor (on page 47). Data type: string.

Note: This descriptor contains permissions extensions. For details, refer to the Extension of Permissions Descriptor (on page 51) section.

Supported Operations

481

Response Samples
A positive response from the server can look as follows:
<packet version="1.5.0.0"> <domain> <get-permission-descriptor> <result> <status>ok</status> <filter-id>MyDomain.com</filter-id> <id>10</id> <property> <name>manage_sh_access</name> <type>boolean</type> <default-value>false</default-value> <writable-by>admin</writable-by> <label>cl_perm__manage_sh_access</label> <extension> <level>client</level> <level>domain</level> </extension> </property> ... <property> <name>manage_dashboard</name> <type>boolean</type> <default-value>true</default-value> <writable-by>admin</writable-by> <writable-by>client</writable-by> <label>cl_perm__manage_dashboard</label> <extension> <level>client</level> <level>domain</level> </extension> </property> </descriptor> </result> </get-permission-descriptor> </domain> </packet>

If the domain specified in the request packet was not found on the server, the result is as follows:
<packet version="1.5.0.0"> <domain> <get-permission-descriptor> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>MyDomain.com</filter-id> </result> </get-permission-descriptor> </domain> </packet>

482

Supported Operations

Retrieving Descriptor of Hosting Settings


Use the get-physical-hosting-descriptor operation to retrieve descriptor of domain hosting settings. For details on descriptors, refer to the Representation of Object Descriptor (on page 47) section. For details on hosting settings, refer to the Hosting Settings (on page 399) section.

In this section:
Request Packet Structure.................................................................................. 482 Request Samples .............................................................................................. 482 Response Packet Structure ............................................................................... 484 Response Samples ........................................................................................... 485

Request Packet Structure


A request XML packet retrieving descriptor of hosting settings includes the get-physicalhosting-descriptor operation node:
<packet version=1.5.0.0> <domain> <get-physical-hosting-descriptor> </get-physical-hosting-descriptor> </domain> </packet>

You can retrieve descriptor for the specified domain (or multiple domains specified by client ID or login name) or the server-level descriptor of hosting settings. The getphysical-hosting-descriptor node has the following graphical representation:

The filter node is required. It specifies a filtering rule. For info on filters, refer to the Filters of Descriptors (on page 47) section. Data type: domainFilterType (domain_input.xsd).

Supported Operations

483

Request Samples
The request packet retrieving descriptor of hosting settings for the domain with ID 5 looks as follows:
<packet version ="1.5.0.0"> <domain> <get-physical-hosting-descriptor> <filter> <id>5</id> </filter> </get-physical-hosting-descriptor> </domain> </packet>

The request packet retrieving descriptor of hosting settings for MyDomain.com and MySample.com domains looks as follows:
<packet version ="1.5.0.0"> <domain> <get-physical-hosting-descriptor> <filter> <domain_name>5</domain_name> <domain_name>7</domain_name> </filter> </get-physical-hosting-descriptor> </domain> </packet>

The request packet retrieving descriptor of hosting settings for domains of the client specified by ID 3 looks as follows:
<packet version ="1.5.0.0"> <domain> <get-physical-hosting-descriptor> <filter> <client_id>3</client_id> </filter> </get-physical-hosting-descriptor> </domain> </packet>

The request packet retrieving the server-level descriptor of hosting settings looks as follows:
<packet version ="1.5.0.0"> <client> <get-physical-hosting-descriptor> <filter/> </get-physical-hosting-descriptor> </client> </packet>

484

Supported Operations

Response Packet Structure


The get-physical-hosting-descriptor node of the output XML packet is structured as follows:

Supported Operations

485

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (plesk_common.xsd). The status node is required. It specifies the execution status of the get-physicalhosting-descriptor operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get-physicalhosting-descriptor operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the getphysical-hosting-descriptor operation fails. Data type: string. The filter-id node is optional. It is required if the get-physical-hosting-descriptor operation succeeds. Returns either domain name, domain ID, client name, or client ID depending on a way of descriptor's specification in the request packet. This node is available in API RPC 1.5.0.0 and later versions. For info on filters, refer to the Filters of Descriptors (on page 48) section. Data type: anySimple. The id node is optional. It is required if the get-physical-hosting-descriptor operation succeeds. Returns the unique identifier of the domain. Data type: integer. The descriptor node is optional. It specifies the object descriptor. For details, refer to Representation of Object Descriptor (on page 47). Data type: string.

Note: This descriptor contains hosting settings extensions. For details, refer to the Extension of Hosting Settings Descriptor (on page 51) section.

Response Samples
A positive response from the server can look as follows:
<packet version="1.5.0.0"> <domain> <get-physical-hosting-descriptor> <result> <status>ok</status> <filter-id>MyDomain.com</filter-id> <id>15</id> <descriptor> <property> <name>ftp_login</name> <type>string</type> <writable-by>admin</writable-by> <label>hst_def__fp_admin_login</label> </property> <property> <name>fp_admin_password</name> <type>passwordString</type> <writable-by>none</writable-by> <label>hst_def__fp_admin_passwd</label> </property> <property> <name>shell</name> <type>string</type> <enum> <value>/bin/false</value> <label>Forbidden</label> </enum> <enum> <value>/bin/ash</value> <label>/bin/ash</label>

486

Supported Operations </enum> <enum> <value>/bin/bash</value> <label>/bin/bash</label> </enum> ... <enum> <value>/usr/local/psa/bin/chrootsh</value> <label>/bin/bash (chrooted)</label> </enum> <enum> <value>/bin/rbash</value> <label>/bin/rbash</label> </enum> <writable-by>admin</writable-by> <label>hst_def__shell</label> </property>

If the domain specified in the request packet was not found on the server, the result is as follows:
<packet version="1.5.0.0"> <domain> <get-permission-descriptor> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>MyDomain.com</filter-id> </result> </get-permission-descriptor> </domain> </packet>

Supported Operations

487

Managing Domain Aliases


Operator: <domain_alias> XML Schema: domainalias_input.xsd, domainalias_output.xsd Plesk version: Plesk 7.5.6 Win | Unix 8.0 and later API RPC version: 1.4.0.0 and higher Plesk user: Plesk Administrator Description Domain Aliases are alternative names for the domain name. You can also use domain aliases to redirect mail and Java applications from the domain alias to your original domain name. Tomcat (Java) redirection means that the Tomcat server set on the primary domain (port 9080) handles requests coming from domain aliases (from port 9080). Plesk Administrators can manage all domain aliases registered on Plesk server. Note: The Tomcat support is provided from the 1.4.2.0 version of API RPC. Supported operations

488

Supported Operations

CREATE (see page 492) creates an alias for the specified domain GET (see page 497) retrieves the alias settings for the alias specified by ID name, or the primary domain ID, name SET (see page 503) updates the alias settings for the alias specified by ID name, or the primary domain ID, name DELETE (see page 507) removes the specified alias from the domain RENAME (see page 511) renames the alias related to the specified domain GET-SUPPORTED-SERVICES (see page 514) retrieves the list of domain alias supported services which can be managed on the server

Remarks When you set up a domain alias, resource records in its DNS zone are copied from the original domain name. This means that if your original domain points to an external mail server, your domain alias will point to that mail server, too. However, to accept mail for the domain alias, the external mail server should be configured accordingly. Whenever you change mail exchange records in the domain DNS zone, be sure to introduce the respective changes in the DNS zone of the domain alias. If you need to serve several domain names that point to a web site hosted on another server, you should set up domain forwarding.

In this section:
Domain Alias Settings ....................................................................................... 489 Filtering Issues .................................................................................................. 491 Creating Domain Aliases ................................................................................... 492 Retrieving Information On Domain Aliases ........................................................ 497 Updating Domain Aliases Settings .................................................................... 503 Deleting Domain Aliases ................................................................................... 507 Renaming Domain Aliases ................................................................................ 511 Retrieving Information On Manageable Services ............................................... 514

Supported Operations

489

Domain Alias Settings


This section describes settings that can be predefined for a domain alias. These settings can be set on creation of a domain alias, or they can be set for this domain alias later, or read from the database. Domain alias settings are defined by the settings node and presented by type Settings (plesk_domainalias.xsd). It has the following graphics representation:

The status node is optional. It specifies the current status of the domain alias. This node is used only in Plesk for Unix. Data type: byte. Allowed values: 0 (alias enabled) 1 (alias disabled) 2 (primary domain disabled) 3 (alias disabled, primary domain disabled)

The pref node is optional. If specified, it defines the alias form. To specify the alias form, choose between the following options: (API RPC 1.4.2.0 and earlier versions)

(API RPC 1.5.0.0 and later versions)

490

Supported Operations

The web node is used when you want to redirect web content from a domain alias to your original domain. This node is required in API RPC v.1.4.2.0 (and earlier) and optional in API RPC v.1.5.0.0 (and later). Data type: boolean. The mail node is used when you want to redirect mail from a domain alias to your original domain. This node is required in API RPC v.1.4.2.0 (and earlier) and optional in API RPC v.1.5.0.0 (and later) Data type: boolean. The tomcat node is optional. It is used when you want to redirect Java applications from a domain alias to the Tomcat server on the primary domain (Tomcat server port 9080). Tomcat redirection is supported from the 1.4.2.0 version of API RPC. This node is used only in Plesk for Unix. Data type: boolean. The full node is used when you want to create both web, mail and tomcat aliases. Data type: none.

The manage-dns node is optional. It defines if you can manage DNS zone for the domain alias. This node is supported starting from API RPC v.1.5.0.0. Data type: boolean.

Note: Before performing any operations on domain alias settings, be sure to call operation get-supported-services (see page 514) retrieving from server information on which of them are operable. AliasInfoType (plesk_domainalias.xsd) is an extension of the Settings type. It contains the following additional nodes:

The domain_id node is required. It specifies the id of the primary domain. Data type: integer. The name node is required. It specifies the name (in Unicode) of the primary domain. Data type: string. The ascii_name node is optional. It specifies the name (in ASCII) of the primary domain. Data type: string.

Supported Operations

491

Filtering Issues
This section describes some peculiarities of domain alias filtering. Filtering is the way the request XML packet indicates the object (one or several domain aliases) to which the operation will be applied. The request XML filters domain aliases using a special filter section. When created, a domain alias is given a unique identifier and a unique name. Thus, to specify a domain alias (e.g. for the set or get operation), the packet needs a special filter section structured as follows:

The DomainAliasFilterType (domainalias_input.xsd) allows you to specify a domain alias either by id, name, primary domain id, or primary domain name. In addition, it allows you to specify multiple domain aliases within one filter. Finally, the filter can be left empty, which means that all domain aliases are selected. The id node is optional. It specifies the domain alias by id. Data type: integer. The name node is optional. It specifies the domain alias by name. Data type: string (Unicode). The domain_id node is optional. It specifies the domain alias by id of the primary domain. Data type: integer. The domain_name is optional. It specifies the domain alias by name of the primary domain. Data type: string (Unicode).

Note: Use <filter/> to update settings of all domain aliases on the server or delete all domain aliases from the server. For example, a packet that retrieves the information about all domain aliases looks as follows:
<packet version="1.4.2.0"> <domain_alias> <get> <filter/> </get> </domain_alias></packet>

492

Supported Operations

Creating Domain Aliases


Only Plesk Administrator can create domain aliases via API RPC. To create a domain alias, it is enough to specify the domain ID and the domain name. You can also specify alias settings when creating a domain alias (all of them are optional): Alias status Alias preferences

You can specify alias settings during or after creation of an alias. Alias settings can be set using the set (see page 503) operation. To get information on which domain alias settings can be set on a particular server, use the get-supported-services (see page 514) operation.

In this section:
Request Packet Structure.................................................................................. 492 Request Samples .............................................................................................. 494 Response Packet Structure ............................................................................... 496 Response Samples ........................................................................................... 497

Request Packet Structure


A request XML packet creating a new domain alias in Plesk database includes the create operation node:
<packet version="1.4.2.0"> <domain_alias > <create> </create> </domain_alias> </packet>

Supported Operations

493

The create node is presented by the AliasInfoType type (plesk_domainalias.xsd). Its graphical representation is as follows:

The status node is optional. It specifies the status of a domain alias. For more information, see the Domain Alias Settings (see page 489) section. Data type: string. Allowed values: ok | error. The pref node is optional. It specifies preferences of a domain alias. For more information, see the Domain Alias Settings (see page 489) section. Data type: none. The manage-dns node is optional. It defines if you can manage DNS zone for the domain alias.

Note: This node is supported starting from API RPC v.1.5.0.0. Data type: boolean. The domain_id node is required. It specifies the id of the primary domain. Data type: integer. The name node is required. It specifies the name of the primary domain. Data type: string (Unicode). The ascii-name node is optional. It specifies the name of the primary domain. Data type: string (ASCII).

Remarks The ascii-name node is supported by API RPC 1.4.2.0 and later versions.

494

Supported Operations

Request Samples
Creating a single domain alias To create a domain alias, specify the ID of the primary domain (the alias will be linked to) and name of the alias.
<packet version="1.4.2.0"> <domain_alias> <create> <domain_id>12</domain_id> <name>myalias.com</name> </create> </domain_alias> </packet>

Creating multiple domain aliases To create two domain aliases with a single packet, include two different create operations:
<packet version="1.4.2.0"> <domain_alias> <create> <domain_id>12</domain_id> <name>MyAlias.com</name> </create> <create> <domain_id>12</domain_id> <name>MySecondAlias.com</name> </create> </domain_alias> </packet>

Supported Operations

495

Alias settings The following packet creates three domain aliases to the domain with ID 12. The alias settings are as follows: DisabledAlias is disabled. EnabledWebOnlyAlias is enabled and has only web content redirection. DisWebMaillAlias is disabled because the primary domain (ID 12) is disabled and has both mail, web and tomcat redirection.

<packet version="1.4.2.0"> <domain_alias> <create> <status>1</status> <domain_id>12</domain_id> <name>DisabledAlias.com</name> </create> <create> <status>0</status> <pref> <web>1</web> <mail>0</mail> <tomcat>0</tomcat> </pref> <domain_id>12</domain_id> <name>DisabledAlias.com</name> </create> <create> <status>2</status> <pref> <full/> </pref> <domain_id>12</domain_id> <name>DisWebMailAlias.com</name> </create> </domain_alias> </packet>

496

Supported Operations

Response Packet Structure


The create node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: AliasResultType (domainalias_output.xsd). The status node is required. It specifies the execution status of the create operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the create operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the create operation fails. Data type: string. The id node is optional. It returns the ID of the domain alias; it is required if the create operation has succeeded. Returns the unique identifier of the domain alias just added to Plesk. Data type: integer. The name node is optional. It does not hold any value for this operation. This node is absent starting from API RPC v.1.5.0.0. Data type: string.

Supported Operations

497

Response Samples
Creating a single domain alias A positive response received from the server after adding a new domain alias can look as follows:
<packet version="1.4.2.0"> <domain_alias> <create> <result> <status>ok</status> <id>34</id> </result> </create> </domain_alias> </packet>

A negative response can look as follows:


<packet version="1.4.2.0"> <domain_alias> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </add> </domain_alias> </packet>

Retrieving Information On Domain Aliases


The get operation is used to retrieve info on domain aliases from Plesk database that includes the following parameters: Domain alias preferences Primary domain id and name

In this section:
Request Packet Structure ..................................................................................498 Request Samples ..............................................................................................498 Response Packet Structure ...............................................................................500 Response Samples ............................................................................................501

498

Supported Operations

Request Packet Structure


A request XML packet retrieving a domain alias settings from Plesk database includes the get operation node:
<packet version="1.4.2.0"> <domain_alias > <get> </get> </domain_alias> </packet>

The get node graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on filters, refer to the Filtering Issues (see page 491) section. Data type: domainAliasFilterType (domainalias_input.xsd). The id node is optional. It specifies the domain alias by id. Data type: integer. The name node is optional. It specifies the domain alias by name. Data type: string (Unicode). The domain_id node is optional. It specifies the domain alias by ID of the primary domain. Data type: integer. The domain_name is optional. It specifies the domain alias by name of the primary domain. Data type: string (Unicode).

Note: You can create filtering rules for multiple domain_id and domain_name parameters in API RPC 1.4.2.0 and later versions. In the elder versions of API RPC you can use only one domain_id or domain_name in a single filter.

Supported Operations

499

Request Samples
Retrieving settings of a single domain alias This packet retrieves preferences of the domain alias called MyAlias.com.
<packet version="1.4.2.0"> <domain_alias> <get> <filter> <name>MyAlias.com</name> </filter> </get> </domain_alias> </packet>

Retrieving settings of multiple domain aliases This packet retrieves preferences of the domain aliases called MyAlias.com and MySecondAlias.com.
<packet version="1.4.2.0"> <domain_alias> <get> <filter> <name>MyAlias.com</name> <name>MySecondAlias.com</name> </filter> </get> </domain_alias> </packet>

The following packet is wrong because both name and domain_id are used for identification.
<packet version="1.4.2.0"> <domain_alias> <get> <filter> <name>MyAlias.com</name> <domain_id>12</domain_id> </filter> </get> </domain_alias> </packet>

This packet retrieves preferences of all domain aliases on the server.


<packet version="1.4.2.0"> <domain_alias> <get> <filter/> </get> </domain_alias></packet>

500

Supported Operations

Response Packet Structure


The get node of the output XML packet is structured as follows:

The result node is required. It wraps the response received from the server. Data type: resultFilterType (common.xsd). The status node is required. Specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the get operation fails. Data type: string. The id node is optional. It returns the domain alias id; it is required if the get operation has succeeded or if this id was specified in the request packet. Data type: integer. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues section. Data type:anySimple.

Note: In API RPC v.1.4.2.0 and earlier, response packets contain the name node instead of the filter-id node. The name node is optional. It is required if the operation succeeds or if this name was specified in the request packet. The node holds the domain alias name Data type: string. The info node is optional. It is present if the get operation succeeds and contains the alias preferences. For more information, refer to the Domain Alias Settings (see page 489)section. Data type: AliasInfoType (plesk_domainalias.xsd).

Note: If the get operation has succeeded, both id and name nodes are required.

Supported Operations

501

Response Samples
Retrieving settings of a single domain alias A positive response received from the server after retrieving info on the domain alias can look as follows:
<packet version="1.4.2.0"> <domain_alias> <get> <result> <status>ok</status> <id>34</id> <name>MyAlias.com</name> <info> <prefs> <web>true</web> <mail>false</mail> <tomcat>false</tomcat> </prefs> <domain_id>3</domain_id> <name>PrimaryForThisAlias.com</name> <ascii-name>PrimaryForThisAlias.com</ascii-name> </info> </result> </get> </domain_alias> </packet>

If a request packet tried to retrieve settings of the non-existent domain alias (MyAlias.com), the negative response can look as follows:
<packet version="1.4.2.0"> <domain_alias> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Domain alias does not exist</errtext> <name>MyAlias.com</name> </result> </get> </domain_alias> </packet>

502

Supported Operations

Retrieving settings of multiple domain alias A possible request packet is:


<packet version="1.4.2.0"> <domain_alias> <get> <filter> <domain_name>PrimaryDomain.com</domain_name> </filter> </get> </domain_alias> </packet>

A possible negative response got from the server is (the domain name does not exist on the server):
<packet version="1.4.2.0"> <domain_alias> <get> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> </result> </get> </domain_alias> </packet>

A positive response got from the server can look as follows (two domain aliases exist for this domain name):
<packet version="1.4.2.0"> <domain_alias> <get> <result> <status>ok</status> <id>124</id> <name>MyAlias.com</name> <info> <prefs> <web>false</web> <mail>false</mail> <tomcat>false</tomcat> </prefs> <domain_id>3</domain_id> <name>PrimaryDomain.com</name> <ascii-name>PrimaryDomain.com</ascii-name> </info> </result> <result> <status>ok</status> <id>127</id> <name>My2Alias.com</name> <info> <prefs> <web>true</web>

Supported Operations <mail>false</mail> <tomcat>false</tomcat> </prefs> <domain_id>3</domain_id> <name>PrimaryDomain.com</name> <ascii-name>PrimaryDomain.com</ascii-name> </info> </result> </get> </domain_alias> </packet>

503

Updating Domain Aliases Settings


The set operation is used to update settings of domain aliases stored in Plesk database. You can update all settings of a domain alias in bulk or specify some particular settings. To get information on which domain alias settings can be updated on a particular server, use the get-supported-services (see page 514) operation. For more information visit the Domain Alias Settings (see page 489) section.

In this section:
Request Packet Structure.................................................................................. 503 Request Samples .............................................................................................. 504 Response Packet Structure ............................................................................... 505 Response Samples ........................................................................................... 506

Request Packet Structure


A request XML packet changing the domain alias settings in the Plesk database includes the set operation node:
<packet version="1.4.2.0"> <domain_alias> <set> ... </set> </domain_alias> </packet>

The set node graphical representation is as follows:

The filter node specifies which domain aliases will be affected. For more information, refer to the Filtering Issues (see page 491) section. Data type: DomainAliasFilterType (domainalias_input.xsd)

504

Supported Operations

The settings node defines settings to be applied to these domain aliases. For more information, please refer to the Domain Alias Settings (see page 489) section. Data type: Settings (plesk_domainalias.xsd)

Request Samples
Updating settings of a single domain alias This packet sets up Web, Mail and Tomcat references between MyAlias.com and the primary domain.
<packet version="1.4.2.0"> <domain_alias> <set> <filter> <name>MyAlias.com</name> </filter> <settings> <pref> <full/> </pref> </settings> </set> </domain_alias> </packet>

Updating settings of multiple domain aliases This packet switches off mail redirection from domain aliases to the primary domain MyPrimary.com.
<packet version="1.4.2.0"> <domain_alias> <set> <filter> <domain_name>MyPrimary.com</domain_name> </filter> <settings> <pref> <web>1</web> <mail>0</mail> <tomcat>0</tomcat> </pref> </settings> </set> </domain_alias> </packet>

Supported Operations

505

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. Specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the set operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the set operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues section. Data type:anySimple.

Note: In API RPC v.1.4.2.0 and earlier, response packets contain the name node instead of the filter-id node. The name node is optional. It is required if the operation succeeds. The node holds the primary domain name or alias name depending on the name specified in the request packet. Data type: string. The id node is optional. It returns the domain alias ID; it is required if the alias id was specified in the request packet. Data type: integer.

506

Supported Operations

Response Samples
Updating settings of a single domain alias A positive response retrieved from the server after applying domain alias settings can look as follows:
<packet version="1.4.2.0"> <domain_alias> <set> <result> <status>ok</status> <name>MyAlias.com</name> </result> </set> </domain_alias> </packet>

If a request packet tries to apply settings to a non-existent domain alias (id = 13), a negative response will look as follows:
<packet version="1.4.2.0"> <domain_alias> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Domain alias does not exist</errtext> <id>13</id> </result> </set> </domain_alias> </packet>

Updating settings of multiple domain aliases A possible request packet can look as follows:
<packet version="1.4.2.0"> <domain_alias> <set> <filter> <domain_name>MyPrimary.com</domain_name> </filter> <settings> <pref> <full/> </pref> </settings> </set> </domain_alias> </packet>

Supported Operations

507

A possible negative response from the server looks as follows:


<packet version="1.4.2.0"> <domain_alias> <set> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> </result> </set> </domain_alias> </packet>

A possible positive response from the server looks as follows (two domain aliases updated):
<packet version="1.4.2.0"> <domain_alias> <set> <result> <status>ok</status> <id>100</id> <name>MyPrimary.com</name> </result> <result> <status>ok</status> <id>101</id> <name>MyPrimary.com</name> </result> </set> </domain_alias> </packet>

508

Supported Operations

Deleting Domain Aliases


Use the delete operation to remove a specified domain alias from Plesk database.

In this section:
Request Packet Structure.................................................................................. 508 Request Samples .............................................................................................. 509 Response Packet Structure ............................................................................... 510 Response Samples ........................................................................................... 511

Request Packet Structure


A request XML packet removing the domain aliases from Plesk database includes the delete operation node:
<packet version="1.4.2.0"> <domain_alias> <delete> ... </delete> </domain_alias> </packet>

The delete node graphical representation is as follows:

The filter node specifies the filtering rule. For information on filters, refer to the Filtering Issues (see page 491) section. Data type: DomainAliasFilterType (domainalias_input.xsd)

Supported Operations

509

Request Samples
Deleting a single domain alias This packet deletes the MyAlias.com alias:
<packet version="1.4.2.0"> <domain_alias> <delete> <filter> <name>MyAlias.com</name> </filter> </delete> </domain_alias> </packet>

Deleting multiple domain aliases This packet deletes all domain aliases from the primary domains MyPrimary.com and My2Primary.com.
<packet version="1.4.2.0"> <domain_alias> <delete> <filter> <domain_name>MyPrimary.com</domain_name> <domain_name>My2Primary.com</domain_name> </filter> </delete> </domain_alias> </packet>

This packet removes all domain aliases from all domains on the server.
<packet version="1.4.2.0"> <domain_alias> <delete> <filter/> </delete> </domain_alias> </packet>

510

Supported Operations

Response Packet Structure


The delete node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the delete operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the delete operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the delete operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues section. Data type:anySimple.

Note: In API RPC v.1.4.2.0 and earlier, response packets contain the name node instead of the filter-id node. The name node is optional. It is present if the operation succeeds. The node returns the domain alias name. Data type: string. The id node is optional. It returns the domain alias ID; it is required if the operation delete succeeds. Data type: integer.

Supported Operations

511

Response Samples
Deleting a single domain alias The request packet looks as follows:
<packet version="1.4.2.0"> <domain_alias> <delete> <filter> <domain_id>128</domain_id> </filter> </delete> </domain_alias> </packet>

A positive response retrieved from the server can look as follows:


<packet version="1.4.2.0"> <domain_alias> <delete> <result> <status>ok</status> <id>13</id> <name>MyAlias.com</name> </result> <result> <status>ok</status> <id>14</id> <name>My2Alias.com</name> </result> </delete> </domain_alias> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <domain_alias> <delete> <result> <status>error</status> <errcode>1013</errcode> <errtext>Domain does not exist</errtext> <name>MyAlias.com</name> </result> </delete> </domain_alias> </packet>

512

Supported Operations

Renaming Domain Aliases


The rename operation is used to rename the specified domain alias. The domain alias can be specified either by ID, or by name.

In this section:
Request Packet Structure.................................................................................. 512 Request Samples .............................................................................................. 513 Response Packet Structure ............................................................................... 513 Response Samples ........................................................................................... 514

Request Packet Structure


A request XML packet renaming the domain alias in Plesk database includes the rename operation node:
<packet version="1.4.2.0"> <domain_alias> <rename> ... </rename> </domain_alias> </packet>

The rename node graphical representation is as follows:

The id node is required. It specifies the domain alias by ID. Data type: integer. The name node is required. It specifies the domain alias by name. Data type: string (Unicode). The new_name node is required. It is used to assign a new domain alias name. Data type: string (Unicode).

Supported Operations

513

Request Samples
Renaming a domain alias The following XML packet renames the MyAlias.com domain alias to MyNewAlias.com:
<packet version="1.4.2.0"> <domain_alias> <rename> <name>MyAlias.com</name> <new_name>MyNewAlias.com</new_name> </rename> </domain_alias> </packet>

The following XML packet is not valid because it specifies both alias name and id.
<packet version="1.4.2.0"> <domain_alias> <rename> <id>15</id> <name>MyAlias.com</name> </rename> </domain_alias> </packet>

Response Packet Structure


The rename node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the rename operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the rename operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the rename operation fails. Data type: string.

514

Supported Operations

Response Samples
Renaming a domain alias The following packet shows that the domain alias was successfully renamed:
<packet version="1.4.2.0"> <domain_alias> <rename> <result> <status>ok</status> </result> </rename> </domain_alias> </packet>

A negative response can look as follows:


<packet version="1.4.2.0"> <domain_alias> <rename> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </rename> </domain_alias> </packet>

Supported Operations

515

Retrieving Information On Manageable Services


The get-supported-services operation is used to retrieve a list of server services which can be turned on/ off for domain aliases on that server. The number of manageable services on domain aliases differ in Plesk for Unix and Plesk for Windows: You cannot switch Tomcat service for domain aliases in Plesk for Windows. Note: This operation appears in Plesk XML API v.1.4.2.0 and is not supported in previous versions. Request Sample The following XML packet requests which domain alias services can be managed on the server:
<packet version="1.4.2.0"> <domain_alias> <get-supported-services/> </domain_alias> </packet>

Response Samples Response from server that runs Plesk for Unix, showing that all 3 services - Web, Mail and Tomcat - can be enabled/ disabled for domain aliases on the server, looks like:
<packet version="1.4.2.0"> <domain_alias> <get-supported-services> <result> <status>ok</status> <service>web</service> <service>mail</service> <service>tomcat</service> </result> </get-supported-services> </domain_alias> </packet>

Response from server that runs Plesk for Windows, showing that only 2 services - Web and Mail - can be enabled/ disabled for domain aliases on the server, looks like:
<packet version="1.4.2.0"> <domain_alias> <get-supported-services> <result> <status>ok</status> <service>web</service> <service>mail</service> </result> </get-supported-services> </domain_alias> </packet>

516

Supported Operations

Managing Domain Templates


Operator: <domain-template> XML Schema: domain_template.xsd Plesk version: Plesk 8.0 for UNIX | Plesk 7.6 for Windows and higher API RPC version: 1.4.1.0 and higher Plesk user: Plesk Administrator Description Domain templates are a kind of hosting configuration presets which are useful when it is necessary to create multiple domain accounts with identical hosting/mail settings, limits, and other preferences. Settings Domain templates are used to fix a definite collection of domain settings and apply these settings to domains created using these domain templates. These settings are as follows: Hosting settings Mailing settings Limits on use of Plesk resources Preferences Log rotation settings Performance settings

Refer to the Domain Template Settings (see page 517) section for details. Supported operations

ADD (see page 523) creates a domain template and to add it to the list of domain templates for a certain user; GET (see page 532) gets the information on the specified domain template(s) from the server;

Supported Operations

517

DEL (see page 549) deletes the specified domain template (or several); SET (see page 539) sets new settings to the specified domain template.

In this section:
Domain Template Settings ................................................................................ 517 Filtering Issues .................................................................................................. 522 Creating Domain Template................................................................................ 523 Getting Information On Domain Templates ....................................................... 532 Configuring Domain Template Settings ............................................................. 539 Deleting Domain Template ................................................................................ 549

Domain Template Settings


This section describes a collection of domain settings that can be predefined in a domain template. These settings can be set for a domain being created, or they can be set for this domain later, or read from the database. These settings are as follows: Mailing settings (see page 518) Limits, permissions and hosting settings (on page 397) Preferences (see page 520) Log rotation settings (see page 519) Domain performance settings (see page 521)

In this section:
Mailing Settings .................................................................................................518 Log Rotation Settings.........................................................................................519 Preferences .......................................................................................................520 Performance Settings ........................................................................................521

518

Supported Operations

Mailing Settings
Mailing settings are defined in the domain template by the mail node. This node is presented by type MailPreferences (plesk_mailname.xsd). It has the following graphics model:

The nonexistent-user node is optional. If specified, it is used to collect and handle email messages sent to users not registered on the domain. By default, such messages are sent back to the sender with a message: this address no longer accepts mail. To specify the handling method, choose between the following three options: The bounce node is used to modify the default rejection message. Data type: string. The forward node specifies the email addresses to which undelivered mail should be forwarded. Data type: string. The reject node is used to reject such email messages (they will not be accepted by the mail server). Data type: no. The webmail node is optional. It specifies whether mail users will be able to read mail through the WebMail application. Data type: boolean.

Supported Operations

519

Log Rotation Settings


The idea of log rotation is as follows. Active log files can be handled daily, weekly, monthly, or when some log file grows too large (the maximal size can be restricted). Before being handled, the active log file is removed from logging and a new one is created. Plesk starts logging to the new log file, while the dropped-out log file is handled, compressed, and emailed to some address (if this action is specified). The handled log files are stored on the server. The number of such stored files is limited. Once the limit is exceeded, the oldest file is removed from the server and a new handled log file is added. Log rotation settings are specified in the log-rotation node defined by complex type LogRotationType (domain_template.xsd). It is structured as follows:

The off node is required if the on node is not specified. This node disables log rotation on a domain created using this domain template. Data type: none. The on node is required if the off node is not specified. This node enables log rotation on a domain created using this domain template. Data type: none. The log-condition type is required if the on node is specified. Specifies the criterion for triggering log rotation on a domain. Data type: none. The log-bysize type is required if the on node is specified and the log-bytime node is not. Indicates that log files should be handled once the specified size (in Kb) is achieved. Data type: integer. The log-bytime type is required if the on node is specified and the log-bysize node is not. Indicates that log files should be handled periodically. Data type: string. Allowed values: Daily | Weekly | Monthly.

520

Supported Operations

The log-max-num-files node is optional. Specifies the maximal number of handled log files belonging to the domain that can be stored on the server. Data type: integer. The log-compress node is optional. Enables/disables log file compression. Data type: Boolean. The log-email node is optional. Specifies the email address to which the handled log file can be sent. Data type: string.

Note: In API RPC 1.5.0.0 and earlier versions, the type of this node is emailType (common.xsd).

Preferences
Domain preferences set in the domain template are defined by the preferences node. This node is specified by complex type DomainTemplatePreferencesType (domain_templates.xsd). It is structured as follows:

The stat node is optional. Specifies the number of months for which the traffic statistics should be kept for a domain. Data type: integer. The maillists node is optional. Enables/disables the use of mailing lists on a domain created using this domain template. Data type: Boolean. The dns_zone_type node is optional. Specifies the type of DNS zone for a domain created using this domain template. Data type: ZoneType (string). Allowed values: master | slave. The shared node is optional. It indicates whether other Plesk users have access to this template. Specify this option only for domain templates created by Plesk Administrator. Data type: boolean. Supported since protocol version 1.6.0.0.

Supported Operations

521

Performance Settings
Performance settings are defined by the performance node. This node is specified by complex type DomainPerformanceType (plesk_domain.xsd). This type is structured as follows:

The bandwidth node is optional. It restricts the network use by the specified value (Kb/sec) for the domain created using this domain template. Data type: integer. If set to -1, the bandwidth is unlimited. The max_connections node is optional. It restricts the number of connections by the specified value for the domain created using this domain template. Data type: integer. If set to -1, the number of connections is unlimited.

Note: Domain performance settings are supported in domain templates by API RPC 1.4.2.0 and later. The following sample packet creates a domain template and defines performance settings for domains that will be created using this domain template:
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <gen_setup> <name>newdomain.com</name> <client_id>1234</client_id> <ip_address>123.123.123.123</ip_address> </gen_setup> <performance> <bandwidth>1000</bandwidth> <max_connections>-1</max_connections> </performance> </add> </domain-template> </packet>

522

Supported Operations

Filtering Issues
This topic describes some peculiarities of domain template filtering. Filtering is the way the request XML packet indicates the object (a domain template or several) to which the operation will be applied. The request XML packets filter domain templates using a special filter node and by specifying the owner of the template (if necessary). When created, a domain template is given a unique ID and a unique name. The filter node that filters a domain template is presented by the DomainFilterType complex type (domain_input.xsd). This node is structured as follows:

The name node is required. It specifies the template name. Data type: string. The id node is required. It specifies a unique identifier of the domain template. Data type: integer.

The filter node allows you to specify a domain template either by ID, or by template name. In addition, it allows you to specify multiple domain templates within one filter. All of them should be specified either by ID, or by template names.
<packet version=1.4.2.0> <domain-template> <get> <filter> <name>base_template</name> <name>extra_template</name> </filter> </get> </domain-template> </packet>

Or:
<packet version=1.4.2.0> <domain-template> <get> <filter> <id>12</id> <id>14</id> </filter> </get> </domain-template> </packet>

Supported Operations

523

Finally, the filter can be left empty, which means that all domain templates are selected:

<packet version=1.4.2.0> <domain-template> <get> <filter/> </get> </domain-template> </packet>

Another important issue is the ownership of domain templates. When created by Plesk Administrator for own needs, a domain template gets to the administrators template repository. When created for a certain Plesk client, a domain template is added to the template repository of this client.

Domain templates are searched in the template repository of the current user. Since all operations on domain templates are allowed to Plesk Administrator only, domain templates are searched in the administrators repository by default. To filter some domain template that belongs to a certain client, you need to identify this client in the request packet. Use the client-id or client-login node for this purpose:

<packet version=1.4.2.0> <domain-template> <get> <filter> <name>base_template</name> </filter> <client-login>tecnhnolux</client-login> </get> </domain-template> </packet>

524

Supported Operations

Creating Domain Template


A domain template can be created by Plesk Administrator for own needs or for a Plesk client. When creating a domain template, it is enough to specify the template name. If this domain template is created for Plesk client, you also need to specify the client ID or client login. In addition, you can specify various domain settings when creating a domain template (all of them are optional): Hosting settings Mailing settings Limits on use of Plesk resources Preferences Log rotation settings Domain performance settings

You can see all these settings on a domain administrator home page. A domain template can include them all or just some of them. You can specify domain settings when creating a domain template or later (they can be set using the set operation).

In this section:
Request Packet Structure.................................................................................. 525 Request Samples .............................................................................................. 527 Response Packet Structure ............................................................................... 531 Response Samples ........................................................................................... 532

Supported Operations

525

Request Packet Structure


A request XML packet adding a new domain template to Plesk database includes the add operation node:
<packet version=1.4.1.0> <domain-template> <add> </add> </domain-template> </packet>

The add node is presented by type DomainTemplateAddInputType (domain_template.xsd). Its graphical representation is as follows:

The name node is required. It specifies the name of the domain template. Data type: string. The client_id node is optional. It specifies the domain template owner ID. This node is not supported since protocol version 1.6.0.0. Use owner-id node instead.. Data type: integer. The owner-id node is optional. It specifies the ID of the domain template owner. Data type: integer. The node is supported since protocol version 1.6.0.0. The client-login node is optional. It specifies the domain template owner name. Data type: string. This node is not supported since protocol version 1.6.0.0. Use ownerlogin node instead.. Data type: integer.

526

Supported Operations

The owner-login node is optional. It specifies the login name of the domain template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

The mail node is optional. It specifies a collection of email preferences that will be assigned to a new domain created using this template. Data type: MailPreferences (plesk_mailname.xsd). See the structure of this node in the Mailing settings (see page 518) section.

The limits node is optional. It specifies a collection of limits that will be set for new domains created using this template. Data type: domainLimits (plesk_domain.xsd). See the structure of this node in the Limits (on page 397) section.

The log-rotation node is optional. It is used to turn on/off rotation of log files related to a domain created using this template. Data type: LogRotationType (domain_template.xsd). See the structure of this node in the Log Rotation Settings (see page 519) section.

The preferences node is optional. It is used to specify a collection of preferences for new domains created using this template. Data type: DomainTemplatePreferecesType (domain_template.xsd). See the structure of this node in the Preferences (see page 520) section.

The hosting node is optional. Specifies physical hosting settings for new domains created using this template. Data type: DomainTemplatePHostingPreferences (domain_template.xsd). See the structure of this node in the Hosting Settings (on page 397) section.

The performance node is optional. It specifies performance settings for new domains created using this domain template. Data type: DomainPerformanceType (plesk_domain.xsd). This feature is supported by API RPC 1.4.2.0 and later. See the structure of this node in the Performance Settings (see page 521) section.

Supported Operations

527

Request Samples
Creating domain templates for different Plesk users To create a domain template for a certain Plesk user, specify this user either by ID, or by login (both are unique in Plesk).
<packet version=1.6.0.0> <domain-template> <add> <name>base_template</name> <owner-id>12</owner-id> <mail> <webmail>true</webmail> </mail> </add> </domain-template> </packet>

Or:
<packet version=1.6.0.0> <domain-template> <add> <name>base_template</name> <owner-login>JDoe</owner-login> <mail> <webmail>true</webmail> </mail> </add> </domain-template> </packet>

When creating a domain template for Plesk Administrator, nodes owner-id and ownerlogin are not used:
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <mail> <webmail>true</webmail> </mail> </add> </domain-template> </packet>

528

Supported Operations

Creating multiple domain templates To create two domain templates with a single packet, include two different add blocks:
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <mail> <webmail>true</webmail> </mail> </add> <add> <name>quick_template</name> <mail> <webmail>false</webmail> </mail> </add> </domain-template> </packet>

Mailing settings The following packet creates three domain templates. The mailing settings are as follows: bounce_template domain template allows mail users to access the mail service of Plesk (the WebMail application) and specifies the text sent back if a message is addressed to a non-existing user forward_template forwards mail addressed to a non-existing user to a certain mail box reject_template rejects mail addressed to a non-existing user (such messages are not accepted by the mail server)

<packet version=1.4.2.0> <domain-template> <add> <name>bounce_template</name> <mail> <webmail>true</webmail> <nonexistent-user> <bounce>Email address does not exist.</bounce> </nonexistent-user> </mail> </add> <add> <name>forward_template</name> <mail> <nonexistent-user> <forward>spam@technolux.co.uk</forward> </nonexistent-user> </mail> </add> <add> <name>reject_template</name>

Supported Operations <mail> <nonexistent-user> <reject/> </nonexistent-user> </mail> </add> </domain-template> </packet>

529

Log rotation To disable log rotation on a domain created using the specified template, use the following packet:
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <log-rotation> <off/> </log-rotation> </add> </domain-template> </packet>

The following packet creates the domain template that enables log rotation on a domain, allows the storage of up to 30 handled log files related to this domain, and removes active log files related to this domain from logging once a week:
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <log-rotation> <on> <log-condition> <log-bytime>weekly</log-bytime> </log-condition> <log-max-num-files>30</log-max-num-files> <log-compress>true</log-compress> </on> </log-rotation> </add> </domain-template> </packet>

530

Supported Operations

Preferences The following packet creates a domain template and specifies preferences for domains created on its basis.
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <preferences> <stat>6</stat> <maillists>true</maillists> <dns_zone_type>master</dns_zone_type> </preferences> </add> </domain-template> </packet>

Hosting Here is the sample packet that creates a domain template and specifies physical hosting settings for domains that will be created using this domain template.
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <hosting> <ftp_quota>100000</ftp_quota> <ssl>true</ssl> <php>true</php> <php_safe_mode>true</php_safe_mode> <ssi>true</ssi> <cgi>true</cgi> <mod_perl>true</mod_perl> <mod_python>true</mod_python> <webstat>webalizer</webstat> <errdocs>true</errdocs> </hosting> </add> </domain-template> </packet>

Supported Operations

531

Performance settings Here is the sample packet that creates a domain template and specifies performance settings for domains that will be created using this domain template.
<packet version=1.4.2.0> <domain-template> <add> <name>base_template</name> <performance> <bandwidth>1000</bandwidth> <max_connections>20</max_connections> </performance> </add> </domain-template> </packet>

Response Packet Structure


The add node of the output XML packet is structured as follows:

The result node is required. It wraps the response got from the server. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the add operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Returns the error code when the add operation fails. Data type: unsignedInt. The errtext node is optional. Returns the error message if the add operation fails. Data type: string. The id node is optional. It is required if the add operation has succeeded. Returns the unique identifier of the domain template just added to Plesk. Data type: integer.

532

Supported Operations

Response Samples
A positive response got from the server after adding a new domain template can look as follows:
<packet version=1.4.2.0> <domain-template> <add> <result> <status>ok</status> <id>2435</id> </result> </add> </domain-template> </packet>

A negative response can look as follows:


<packet version=1.4.2.0> <domain-template> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </add> </domain-template> </packet>

Getting Information On Domain Templates


The get operation is used to retrieve the information about the domain templates from Plesk database. This information is as follows: Domain template ID and name Hosting settings Mailing settings Limits on use of Plesk resources Preferences Log rotation settings Domain performance settings

The get operation returns all settings currently present in the database in bulk. You cannot request for a definite item of the above list. For instance, you cannot retrieve only hosting settings, only preferences, and so on.

Supported Operations

533

All settings are optional and can be missing. A domain template can even be empty (specified by its ID and name and not containing any other information). The get operation will return only the settings currently stored in the database. Note: If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions and you request info on domain templates owned by a reseller using get, Plesk will return info on only reseller's personal domain templates excluding those owned by the reseller's clients. To retrieve info on domain templates owned by Plesk Administrator, specify artificial client account login name in the filtering rule.

In this section:
Request Packet Structure.................................................................................. 533 Request Samples .............................................................................................. 534 Response Packet Structure ............................................................................... 536 Response Samples ........................................................................................... 538

Request Packet Structure


A request XML packet getting information about the specified domain templates includes the get operation node:
<packet version=1.4.2.0> <domain-template> <get> </get> </domain-template> </packet>

The get node is presented by type DomainTemplateGetInputType (domain_template.xsd). Its graphical representation is as follows:

The filter node is required. It serves to specify the criteria by which the necessary domain templates will be selected from the database. Data type: DomainTemplateFilterType (domain_template.xsd).

534

Supported Operations

The name node is optional. It specifies the names of the domain templates to be selected. Data type: string. The id node is optional. It specifies the unique identifier of domain template to be selected. Data type: integer. The client_id node is optional. It specifies the domain template owner ID. This node is not supported since protocol version 1.6.0.0. Use owner-id node instead.. Data type: integer. The owner-id node is optional. It specifies the ID of the domain template owner. Data type: integer. The node is supported since protocol version 1.6.0.0. The client-login node is optional. It specifies the domain template owner name. Data type: string. This node is not supported since protocol version 1.6.0.0. Use ownerlogin node instead.. Data type: integer. The owner-login node is optional. It specifies the login name of the domain template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

Request Samples
If you work in Plesk 9 backward compatibility mode, the following packet will request info on all domain templates owned by Plesk Administrator:
<packet version=1.5.2.0> <domain-template> <get> <filter> <client_login>admin</client_login> </filter> </get> </domain-template> </packet>

Getting domain templates that belong to different Plesk user To get the information about a domain template that belongs to some Plesk client, specify Plesk client either by ID, or by login.
<packet version=1.6.0.0> <domain-template> <get> <filter> <name>base_template</name> </filter> <owner-login>JDoe</owner-login> </get> </domain-template> </packet>

Supported Operations

535

The following packet retrieves the same information using Plesk reseller ID:
<packet version=1.4.2.0> <domain-template> <get> <filter> <name>base_template</name> </filter> <owner-id>1234</owner-id> </get> </domain-template> </packet>

To retrieve information about a domain template that belongs to Plesk Administrator, use the following packet:
<packet version=1.4.2.0> <domain-template> <get> <filter> <name>base_template</name> </filter> </get> </domain-template> </packet>

Operating multiple domain templates A single filter can specify multiple template instances, all specified either by ID or by the template name.
<packet version=1.4.2.0> <domain-template> <get> <filter> <name>base_template</name> <name>quick_template</name> </filter> </get> </domain-template> </packet>

The following packet sample is wrong:


<packet version=1.4.2.0> <domain-template> <get> <filter> <name>base_template</name> <id>12</id> </filter> </get> </domain-template> </packet>

536

Supported Operations

The following packet gets the information about all domain templates that belong to a definite Plesk client:
<packet version=1.4.2.0> <domain-template> <get> <filter/> <client-login>tecnhnolux</client-login> </get> </domain-template> </packet>

The following packet gets the information about all domain templates that belong to Plesk Administrator:
<packet version=1.4.2.0> <domain-template> <get> <filter/> </get> </domain-template> </packet>

Response Packet Structure


The get node of the output XML packet is structured as follows:

Supported Operations

537

The result node is required. It wraps the information for one domain template. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the get operation. Data type: result_status (string). Allowed values: ok | error. The errcode node is optional. Is required if the get operation fails. Returns the error code. Data type: unsignedInt. The errtext node is optional. Returns the error message. Data type: string. The id node is optional. If the request packet fails before the execution, this node is missing in the response packet. In all other cases it holds the identifier of the domain template (if this id was specified in the request packet). Data type: integer. The name node is optional. If the request packet fails before the execution, this node is missing in the response packet. In all other cases it holds the name of the domain template (if this name was specified in the request packet). Data type: string. The mail node is optional. Is present if the get operation succeeds and mailing settings are defined for this domain template, otherwise is missing in the packet. Data type: MailPreferences (plesk_mailname.xsd). See the structure of this node in the Mailing settings (see page 518) topic. The limits node is optional. Is present if the get operation succeeds and limits are defined for this domain template, otherwise is missing in the packet. Data type: domainLimits (plesk_domains.xsd). See the structure of this node in the Limits (on page 397) topic. The log-rotation node is optional. Is present if the get operation succeeds and log rotation settings are defined for this domain template, otherwise is missing in the packet. Data type: LogRotationType (domain_template.xsd). See the structure of this node in the Log rotation settings (see page 519)topic. The preferences node is optional. Is present if the get operation succeeds and preferences are defined for this domain template, otherwise is missing in the packet. Data type: DomainTemplatePreferencesType (domain_templates.xsd). See the structure of this node in the Preferences (see page 520)topic. The hosting node is optional. Is present if the get operation succeeds and physical hosting settings are defined for this domain template, otherwise is missing in the packet. Data type: DomainTemplatePHosting (domain_templates.xsd). See the structure of this node in the Hosting settings (on page 397) topic. The performance node is optional. This node is supported by API RPC 1.4.2.0 and later. This node is present if the get operation succeeds and performance settings are defined for this domain template, otherwise it is missing in the packet. Data type: DomainPerformanceType (plesk_domain.xsd). See the structure of this node in the Performance settings (see page 521) topic.

538

Supported Operations

Response Samples
The request packet sent to Plesk is as follows:
<packet version=1.6.0.0> <domain-template> <get> <filter> <id>11</id> <id>12</id> </filter> <owner-login>tecnhnolux</owner-login> </get> </domain-template> </packet>

This packet requests for the information about two domain templates specified by ID. A positive response can look as follows:
<packet version=1.6.0.0> <domain-template> <get> <result> <status>ok</status> <id>11</id> <name>base_template</name> <mail> <webmail>true</webmail> </mail> </result> <result> <status>ok</status> <id>12</id> <name>quick_template</name> <limits> <disk_space>209715200</disk_space> <max_traffic>209715200</max_traffic> <max_db>50</max_db> <mysql_dbase_space>52428800</mysql_dbase_space> <expiration>63072000</expiration> </limits> <hosting> <vrt_hst> <ftp_quota>1000000</ftp_quota> <ssl>true</ssl> <php>true</php> <php_safe_mode>true</php_safe_mode> <ssi>true</ssi> <cgi>true</cgi> <mod_perl>true</mod_perl> <mod_python>true</mod_python> <webstat>webalizer</webstat> <errdocs>true</errdocs> </vrt_hst> </hosting> </result> </get> </domain-template> </packet>

Supported Operations

539

The base_template domain template holds the mailing settings only, while the quick_template domain template holds the limits and hosting settings. A negative response can look as follows:
<packet version=1.6.0.0> <domain-template> <get> <result> <status>ok</status> <id>11</id> <name>base_template</name> <mail> <webmail>true</webmail> </mail> </result> <result> <status>error</status> <id>12</id> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> </get> </domain-template> </packet>

Configuring Domain Template Settings


The set operation is used to update domain settings set in the domain templates and stored in Plesk database. This information is as follows: Hosting settings E-mail settings Limits on use of Plesk resources by this domain Preferences Log rotation settings Domain performance settings

You can update all settings of a domain template in bulk or specify some particular settings. Filtering domain templates is made either by the domain template identifier, or by the domain template name. Also, the same packet can handle domain templates and templates belonging to different Plesk users. Proceed to the Filtering Issues (see page 522)topic for details.

In this section:
Request Packet Structure.................................................................................. 540 Request Samples .............................................................................................. 541 Response Packet Structure ............................................................................... 547 Response Samples ........................................................................................... 548

540

Supported Operations

Request Packet Structure


A request XML packet adjusting domain template settings includes the set operation node:
<packet version=1.4.2.0> <domain-template> <set> </set> </domain-template> </packet>

The set node is presented by type DomainTemplateSetInputType (domain_template.xsd). Its graphical representation is as follows:

The filter node is required. It serves to specify the criteria by which domain templates will be updated in the database. Data type: DomainTemplateFilterType (domain_template.xsd). The name node is optional. It specifies the names of domain templates to be updated. Data type: string. The id node is optional. It specifies the unique identifiers of domain templates to be updated. Data type: integer. The client_id node is optional. It specifies the domain template owner ID. This node is not supported since protocol version 1.6.0.0. Use owner-id node instead.. Data type: integer. The owner-id node is optional. It specifies the ID of the domain template owner. Data type: integer. The node is supported since protocol version 1.6.0.0. The client-login node is optional. It specifies the domain template owner name. Data type: string. This node is not supported since protocol version 1.6.0.0. Use ownerlogin node instead.. Data type: integer.

Supported Operations

541

The owner-login node is optional. It specifies the login name of the domain template owner. Data type: string. The node is supported since protocol version 1.6.0.0. The mail node is optional. It sets a collection of email preferences that will be updated for the specified domain templates. Data type: MailPreferences complex type (plesk_mailname.xsd). See the structure of this node in the Mailing settings (see page 518) section. The limits node is optional. It sets a collection of limits that will be updated for the specified domain templates. Data type: domainLimits complex type (plesk_domain.xsd). See the structure of this node in the Limits (on page 397) section. The log-rotation node is optional. It sets a collection of log file rotation settings for the specified domain templates. Data type: LogRotationType complex type (domain_template.xsd). See the structure of this node in the Log rotation settings (see page 519)section. The preferences node is optional. It sets a collection of preferences for the specified domain templates. Data type: DomainTemplatePreferecesType complex type (domain_template.xsd). See the structure of this node in the Preferences (see page 520)section. The hosting node is optional. Sets physical hosting settings for the specified domain templates. Data type: DomainTemplatePhosting (domain_template.xsd). See the structure of this node in the Hosting settings (on page 397) section. The performance node is optional. Sets domain performance settings to the specified domains. Data type: DomainPerformanceType (plesk_domain.xsd). This node is supported by API RPC 1.4.2.0 and later. See the structure of this node in the Performance settings (see page 521) section.

Request Samples
Update domain templates that belong to different Plesk user To update settings of a domain template that belongs to a Plesk user, specify his ID, or by login.
<packet version=1.6.0.0> <domain-template> <set> <filter> <name>base_template</name> </filter> <owner-login>JDoe</owner-login> <mail> <webmail>true</webmail> </mail> </set> </domain-template> </packet>

542

Supported Operations

Another example is:


<packet version=1.6.0.0> <domain-template> <set> <filter> <name>base_template</name> </filter> <owner-id>1234</owner-id> <mail> <webmail>true</webmail> </mail> </set> </domain-template> </packet>

To update settings of a domain template that belongs to Plesk Administrator, do not specify nodes owner-id and owner-login:
<packet version=1.6.0.0> <domain-template> <set> <filter> <name>base_template</name> </filter> <mail> <webmail>true</webmail> </mail> </set> </domain-template> </packet>

Operating multiple domain templates Here is the sample packet that sets similar domain template settings for two different domain templates, both specified by ID.
<packet version=1.6.0.0> <domain-template> <set> <filter> <id>11</id> <id>12</id> </filter> <mail> <webmail>true</webmail> </mail> </set> </domain-template> </packet>

Supported Operations

543

To set different settings for two domain templates, use two different set operations:
<packet version=1.6.0.0> <domain-template> <set> <filter> <id>12</id> </filter> <owner-login>JDoe</owner-login> <mail> <webmail>false</webmail> </mail> </set> <set> <filter> <name>base_template</name> </filter> <mail> <webmail>true</webmail> </mail> </set> </domain-template> </packet>

The following packet updates all domain templates belonging to a Plesk client:
<packet version=1.6.0.0> <domain-template> <set> <filter/> <owner-login>JDoe</owner-login> <mail> <webmail>false</webmail> </mail> </set> </domain-template> </packet>

The following packet updates all domain templates that belong to Plesk Administrator:
<packet version=1.6.0.0> <domain-template> <set> <filter/> <mail> <webmail>false</webmail> </mail> </set></domain-template> </packet>

544

Supported Operations

Mailing settings The following packet updates mailing settings of three domain templates that belong to Plesk Administrator. The new mailing settings are as follows: bounce_template allows email users to access the email service of Plesk (the WebMail application) and edit the text sent back if a message is addressed to a non-existing user forward_template forwards mail addressed to a non-existing user to a certain email box reject_template rejects mail addressed to a non-existing user (such messages are not accepted by the mail server)

<packet version=1.6.0.0> <domain-template> <set> <filter> <name>bounce_template</name> </filter> <mail> <webmail>true</webmail> <nonexistent-user> <bounce>Email address you specified does not exist.</bounce> </nonexistent-user> </mail> </set> <set> <filter> <name>forward_template</name> </filter> <mail> <nonexistent-user> <forward>spam@technolux.co.uk</forward> </nonexistent-user> </mail> </set> <set> <filter> <name>reject_template</name> </filter> <mail> <nonexistent-user> <reject/> </nonexistent-user> </mail> </set> </domain-template> </packet>

Supported Operations

545

Setting limits
<packet version=1.6.0.0> <domain-template> <set> <filter> <id>12</id> </filter> <limits> <disk_space>2048</disk_space> <max_traffic>10240</max_traffic> <max_db>50</max_db> <mysql_dbase_space>1024</mysql_dbase_space> <expiration>63072000</expiration> </limits> </set> </domain-template> </packet>

Log rotation To disable log rotation in the specified template, use the following packet:
<packet version=1.6.0.0> <domain-template> <set> <filter> <id>12</id> </filter> <log-rotation> <off/> </log-rotation> </set> </domain-template> </packet>

The following packet enables log file rotation on a domain created using this domain template, allows the storage of up to 30 handled log files related to this domain, and removes active log files related to this domain from logging once a week:
<packet version=1.6.0.0> <domain-template> <set> <filter> <id>12</id> </filter> <log-rotation> <on> <log-condition> <log-bytime>weekly</log-bytime> </log-condition> <log-max-num-files>30</log-max-num-files> <log-compress>true</log-compress> </on> </log-rotation> </set> </domain-template></packet>

546

Supported Operations

Preferences The following packet specifies preferences for a domain template:


<packet version=1.6.0.0> <domain-template> <set> <filter> <id>12</id> </filter> <preferences> <stat>6</stat> <maillists>true</maillists> <dns_zone_type>master</dns_zone_type> </preferences> </set> </domain-template> </packet>

Hosting Here is the sample packet that sets physical hosting settings to a domain template under Plesk client permissions.
<packet version=1.6.0.0> <domain-template> <set> <filter> <id>12</id> </filter> <hosting> <vrt_hst> <ftp_quota>100</ftp_quota> <ssl>true</ssl> <php>true</php> <php_safe_mode>true</php_safe_mode> <ssi>true</ssi> <cgi>true</cgi> <mod_perl>true</mod_perl> <mod_python>true</mod_python> <webstat>webalizer</webstat> <errdocs>true</errdocs> </vrt_hst> </hosting> </set> </domain-template> </packet>

Supported Operations

547

Hosting Here is the sample packet that sets domain performance settings to a domain template under Plesk client permissions.
<packet version=1.4.2.0> <domain-template> <set> <filter> <id>12</id> </filter> <performance> <bandwidth>1000</bandwidth> <max_connections>20</max_connections> </performance> </set> </domain-template> </packet>

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the result of the set operation for a single domain template. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is required if the set operation fails. Returns the error code. Data type: unsignedInt. The errtext node is optional. Can be returned if the set operation fails. Returns the error message. Data type: string. The id node is optional. If the request packet fails before the execution, this node is missing in the response packet. In all other cases it holds the identifier of the domain template (if this id was specified in the request packet). Data type: integer.

548

Supported Operations

The name node is optional. If the request packet fails before the execution, this node is missing in the response packet. In all other cases it holds the name of the domain template (if this name was specified in the request packet). Data type: string.

Response Samples
A request packet sent to Plesk server can look as follows:
<packet version=1.4.2.0> <domain-template> <set> <filter> <id>11</id> <id>12</id> </filter> <mail> <webmail>false</webmail> </mail> </set> </domain-template> </packet>

This packet updates two domain templates specified by ID. A positive response is sent back if the requested operation succeeds:
<packet version=1.4.2.0> <domain-template> <set> <result> <status>ok</status> <id>11</id> </result> <result> <status>ok</status> <id>12</id> </result> </set> </domain-template> </packet>

Supported Operations

549

A negative response is returned if any domain template failed to be updated:


<packet version=1.4.2.0> <domain-template> <set> <result> <status>ok</status> <id>11</id> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <id>12</id> </result> </set> </domain-template> </packet>

Deleting Domain Template


The del operation is used to remove domain templates. A domain template can be deleted Plesk Administrator only.

In this section:
Request Packet Structure.................................................................................. 549 Request Samples .............................................................................................. 551 Response Packet Structure ............................................................................... 553 Response Samples ........................................................................................... 554

Request Packet Structure


A request XML packet deleting domain templates from Plesk database includes the del operation node:
<packet version=1.4.2.0> <domain-template> <del> </del> </domain-template> </packet>

550

Supported Operations

The del node is presented by type DomainTemplateAddInputType (domain_template.xsd). Its graphical representation is as follows:

The filter node is required. It serves to specify the criteria by which the necessary domain templates will be deleted from the database. Data type: DomainTemplateFilterType (domain_template.xsd). For details on the criteria, see the Filtering Issues section (see page 522). The client_id node is optional. It specifies the domain template owner ID. This node is not supported since protocol version 1.6.0.0. Use owner-id node instead.. Data type: integer. The owner-id node is optional. It specifies the ID of the domain template owner. Data type: integer. The node is supported since protocol version 1.6.0.0. The client-login node is optional. It specifies the domain template owner name. Data type: string. This node is not supported since protocol version 1.6.0.0. Use ownerlogin node instead. Data type: integer. The owner-login node is optional. It specifies the login name of the domain template owner. Data type: string. The node is supported since protocol version 1.6.0.0.

Supported Operations

551

Request Samples
Deleting domain templates that belong to different Plesk user To delete a domain template that belongs to a certain Plesk user, specify the user ID, or login.
<packet version=1.6.0.0> <domain-template> <del> <filter> <name>base_template</name> </filter> <owner-login>JDoe</owner-login> </del> </domain-template> </packet>

The following packet specifies a Plesk user by ID:


<packet version=1.6.0.0> <domain-template> <del> <filter> <name>base_template</name> </filter> <owner-id>1234</owner-id> </del> </domain-template> </packet>

To delete a domain template that belongs to Plesk Administrator, do not specify nodes owner-id and owner-login:
<packet version=1.6.0.0> <domain-template> <del> <filter> <name>base_template</name> </filter> </del> </domain-template> </packet>

552

Supported Operations

Deleting multiple domain templates A single filter can specify multiple template instances for deletion, all defined either by ID or by the template name:
<packet version=1.6.0.0> <domain-template> <del> <filter> <name>base_template</name> <name>quick_template</name> </filter> </del> </domain-template> </packet>

To delete templates that belong to different Plesk users, use a separate del operation for each:
<packet version=1.6.0.0> <domain-template> <del> <filter> <name>base_template</name> <name>quick_template</name> </filter> </del> <del> <filter> <id>52</id> <id>53</id> </filter> <owner-login>JDoe</owner-login> </del> <del> <filter> <id>66</id> <id>67</id> </filter> <owner-id>12134</owner-id> </del> </domain-template> </packet>

The following packet deletes all domain templates belonging to the specified Plesk user:
<packet version=1.6.0.0> <domain-template> <del> <filter/> <owner-login>JDoe</owner-login> </del> </domain-template> </packet>

Supported Operations

553

The following packet deletes all domain templates that belong to Plesk Administrator:
<packet version=1.6.0.0> <domain-template> <del> <filter/> </del> </domain-template> </packet>

Response Packet Structure


The del node of the output XML packet is structured as follows:

The result node is required. It wraps the result of the del operation for a single domain template. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is required if the del operation fails. Returns the error code. Data type: unsignedInt. The errtext node is optional. Returns the error message. Data type: string. The id node is optional. If the request packet fails before the execution, this node is missing in the response packet. In all other cases it holds the identifier of the domain template (if this ID was specified in the request packet). Data type: integer. The name node is optional. If the request packet fails before the execution, this node is missing in the response packet. In all other cases it holds the name of the domain template (if this name was specified in the request packet). Data type: string.

554

Supported Operations

Response Samples
A request packet that orders a del operation is as follows:
<packet version=1.6.0.0> <domain-template> <del> <filter> <id>11</id> <id>12</id> </filter> <owner-login>JDoe</owner-login> </del> </domain-template> </packet>

This packet deletes two domain templates specified by ID. A positive response got from Plesk server can look as follows:
<packet version=1.6.0.0> <domain-template> <del> <result> <status>ok</status> <id>11</id> </result> <result> <status>ok</status> <id>12</id> </result> </del> </domain-template> </packet>

A negative response can look as follows:


<packet version=1.6.0.0> <domain-template> <del> <result> <status>ok</status> <id>11</id> </result> <result> <status>error</status> <id>12/<id> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> </del> </domain-template> </packet>

Supported Operations

555

Managing FTP Accounts


Operator: <ftp-user> XML Schema: ftpuser.xsd Plesk version: Plesk 8.1 for Windows API RPC version: 1.4.2.0 Plesk user: Plesk Administrator, Plesk client Description Generally speaking, Plesk supports two types of FTP accounts: default and additional. The ftp-user operator affects only additional FTP accounts, accounts of the 'default' type are managed with the domain (see page 377) and webuser (see page 1284) operators. Default FTP accounts are the following: Domain user's account (see page 409), which gives access to the whole domain directory. It is always created in Plesk during creating new domain account. Subdomain user's account, which gives access to subdomain directory located in parent domain directory. It is created if the 'Create a separate FTP user account for this subdomain' option was defined while creating a subdomain. Web user's account (see page 1285), which gives access to web user's directory located in domain directory. It is always created in Plesk during creating new web user.

Additional FTP accounts are FTP accounts that can be created and used in addition to default ones. They bring flexibility to managing FTP access to domains, allowing users - other than domain, subdomain and web user - to access particular domain directory with particular rights. Plesk Administrators can manage FTP accounts on all domains. Plesk clients can manage FTP accounts on all domains created for their account on conditions that they are granted the FTP subaccount management permission (see page 74). Supported operations

556

Supported Operations

ADD (see page 560) creates FTP account on a domain specified by its name or ID SET (see page 575) changes properties of a specified FTP account DEL (see page 582) deletes FTP account from a specified domain GET (see page 568) retrieves information on properties of specified FTP accounts on particular domains

In this section:
FTP Account Permissions ..................................................................................556 Filtering Issues...................................................................................................556 Creating FTP Accounts ......................................................................................560 Retrieving Information On FTP Accounts ...........................................................568 Changing FTP Account Settings ........................................................................575 Deleting FTP Accounts ......................................................................................582

FTP Account Permissions


FTP account permissions are presented by type FtpUserPermissions (ftpuser.xsd). It is structured as follows:

The read node is optional. It specifies if the FTP user has read permissions for his home directory (i.e., list folders and files and download files located in it). Data type: boolean. The write node is optional. It specifies if the FTP user has write permissions for his home directory (i.e., create and delete folders, upload, delete and append files). Data type: boolean.

Filtering Issues
Filtering is the way the request packets pick out FTP accounts to which the requested operation will be applied.

In this section:
Filtering in Requests.......................................................................................... 557 Filtering in Responses ....................................................................................... 559

Supported Operations

557

Filtering in Requests
The filter node is presented by the FtpUserFilterType complex type (ftpuser.xsd). This data type is structured as follows:

The id node is required. It specifies the FTP account ID in Plesk database. Data type: integer. The name node is required. It specifies the name of FTP account. Data type: string. The domain-id node is required. It specifies the unique identifier of the domain on which the FTP account exists. Data type: integer. The domain-name node is required. It specifies the name of the domain (in Unicode) on which the FTP account exists. Data type: string.

The filter allows two kinds of filtering: Nodes id and name serve to filter one to many FTP accounts individually. Individual filtering is allowed to Plesk Administrator, Plesk client (on their own domains) and Plesk Domain Administrators (on their own domain). Nodes domain-id and domain-name serve to filter all FTP accounts on a certain domain (or several) at one stroke. This kind of filtering is allowed to Plesk Administrator, and Plesk client (on their own domains).

Individual filtering The following packet requests information on properties of three FTP accounts specified by their ID:
<packet version=1.4.2.0> <ftp-user> <get> <filter> <id>65</id> <id>66</id> <id>67</id> </filter> </get> </ftp-user> </packet>

558

Supported Operations

The following packet is identical except it specifies accounts by their names:


<packet version=1.4.2.0> <ftp-user> <get> <filter> <name>willy</name> <name>billy</name> <name>dilly</name> </filter> </get> </ftp-user> </packet>

The following packet is invalid as both the id and the name nodes are used in the same filter:
<packet version=1.4.2.0> <ftp-user> <get> <filter> <name>willy</name> <id>66</id> <name>dilly</name> </filter> </get> </ftp-user> </packet>

Bulk filtering The following packet deletes all FTP accounts existing on domains specified by ID:
<packet version=1.4.2.0> <ftp-user> <del> <filter> <domain-id>638</domain-id> <domain-id>1498</domain-id> </filter> </del> </ftp-user> </packet>

The same packet specifies domains by name:


<packet version=1.4.2.0> <ftp-user> <del> <filter> <domain-name>doe1.com</domain-name> <domain-name>doe2.com</domain-name> </filter> </del> </ftp-user> </packet>

Supported Operations

559

The following packet is invalid as it uses both the domain-id and the domain-name nodes within one filter:
<packet version=1.4.2.0> <ftp-user> <del> <filter> <domain-id>638</domain-id> <domain-name>doe2.com</domain-name> </filter> </del> </ftp-user> </packet>

The following packet sent by Plesk Administrator deletes all FTP accounts existing in Plesk. If sent by Plesk client, it deletes all FTP accounts on all domains of this Client, if by Plesk Domain Administrator, on his domain.
<packet version=1.4.2.0> <ftp-user> <del> <filter/> </del> </ftp-user> </packet>

Filtering in Responses

If an operation in a request packet (del, get, set) uses filters, the filter-id node is nested in a response packet. It returns the filtering rule. If one of the following values was set as a filter rule, it is returned as the filter-id value in the response packet: FTP account ID FTP account name Domain ID Domain name

It is done so to trace the request parameters in case of an error. Data type: anySimple. The node value can be integer (domain or FTP account ID) or a string (domain or FTP account name). If the filter node is left blank (<filter/>), the filter-id parameter will hold the ID of the object. The blank filter means that all objects are matched by this rule. Note: The filter-id node appears in API RPC 1.4.2.0. Earlier versions of the protocol do not support this node (it is optional for them).

560

Supported Operations

Creating FTP Accounts


To create an FTP account on a domain, use the add operation. The number of accounts that can be created on a particular domain is restricted with the 'Maximum number of additional FTP accounts domain limit (see page 397), or/and by client limit (see page 71) of the same name.

Note: Plesk clients can specify quota on disk space used by home directory only if they are granted the Hard disk quota assignment permission (see page 74).

In this section:
Request Packet Structure.................................................................................. 560 Request Samples .............................................................................................. 563 Response Packet Structure ............................................................................... 565 Response Samples ........................................................................................... 566

Request Packet Structure


A request XML packet creating FTP account on a domain includes the add operation node:

<packet version=1.4.2.0> <ftp-user> <add> </add> </ftp-user> </packet>

Supported Operations

561

The add node is presented by the FtpUserAddInputType complex type (ftpuser.xsd). The node has the following graphical representation:

The name node is required. It specifies the name under which the FTP account will be known in Plesk, and the account login. Data type: string. The password node is required. It specifies the FTP account password. Data type: string. The home node is required. It specifies the home directory of the account, i.e., the directory access to which is granted for the account user. Data type: string. The create-non-existent node is optional. It specifies if the home directory should be created or not. This node with value true is required if the home directory defined by the home node does not exist on the domain. Data type: boolean. The quota node is optional. It specifies the maximum total size of files and folders (in bytes) that the FTP account user can create in or upload to the home directory. Data type: integer. The permissions node is optional. It specifies the FTP account permissions for home directory. For more information, refer to section FTP Account Permissions (see page 556). Data type: FtpUserPermissions. The domain-id node is required. It specifies the ID of the domain on which the FTP account is created. Data type: integer. The domain-name node is required. It specifies the name of the domain (in unicode) on which the FTP account is created. Data type: string.

562

Supported Operations

Remarks 1. FTP account name must be unique in Plesk, meaning that two FTP accounts with the same name cannot be crated, even if you want to crate them on different domains. 2. The default home directory for any new additional FTP account is the domain root directory (namely, "/"). If you want FTP account created with request packet to have a default home directory, include an empty home node to your request:
<home/>

If you want to specify account home directory other than default, in the home node specify a full path to desired directory, starting with root domain directory. For example:
<home>/httpdocs/billy/pub</home>

3. Creating new folders in domain root directory is prohibited by Plesk. Therefore, it is impossible to make some /Global_Upload folder a home directory for an account. Do not include to your packets lines like
<home>/Global_Upload</home> <create-non-existent>true</create-non-existent>

4. To create FTP account with unlimited quota, specify value "-1" in the quota node:
<quota>-1</quota>

5. With one add operation, you can create only one FTP account on a domain specified either by name or by ID. 6. With one packet, you can create as many different FTP accounts on different domains as you want. To create multiple FTP accounts, use the required number of add nodes in the packet.

Supported Operations

563

Request Samples
Creating single FTP accounts This packet creates FTP account, with only required settings specified, on domain with ID "48". The FTP account created with this packet will have name and login ftpuser1 and password jdnHHbe6Gc. User of this account will have access to the domain directory httpdocs, with unspecified permissions. Total size of files that this FTP user is allowed to upload will be limited to default values defined by domain or domain owner limits.
<packet version="1.4.2.0"> <ftp-user> <add> <name>ftpuser1</name> <password>jdnHHbe6Gc</password> <home/> <domain-id>48</domain-id> </add> </ftp-user> </packet>

This packet creates FTP account, with only required settings specified, on domain doe.org. The FTP account created with this packet will have name and login ftpuser2 and password GeNehvs570. User of this account will have access to the directory /httpdocs/Pub which does not exist on the domain and which will be created with this request packet. Total size of files that this FTP user is allowed to upload will be limited to default values defined by domain or domain owner limits.
<packet version="1.4.2.0"> <ftp-user> <add> <name>ftpuser2</name> <password>GeNehvs570</password> <home>/httpdocs/Pub</home> <create-non-existent>true</create-non-existent> <domain-name>doe.org</domain-name> </add> </ftp-user> </packet>

This request packet is incorrect because while creating FTP account it is trying to create the account home directory in domain root folder, and changing the structure of domain root is not allowed by Plesk.
<packet version="1.4.2.0"> <ftp-user> <add> <name>dwarf</name> <password>Kjrnc7HHsn</password> <home>/dwarfyplace</home> <create-non-existent>true</create-non-existent> <domain-name>reddwarf.net</domain-name> </add> </ftp-user> </packet>

564

Supported Operations

This packet creates FTP account, with the full set of settings specified, on domain with ID 50. The account created with this packet will have name and login ftpuser3 and password lkAshr66v. User of this account will have read and write permissions on accessing directory Incoming located in domain folder/httpdocs. Total size of files that this FTP user is allowed to upload will not be limited.
<packet version="1.4.2.0"> <ftp-user> <add> <name>ftpuser3</name> <password>lkAshr66v</password> <home>/httpdocs/Incoming</home> <quota>-1</quota> <permissions> <read>true</read> <write>true</write> </permissions> <domain-id>50</domain-id> </add> </ftp-user> </packet>

Creating multiple FTP accounts This packet creates three FTP accounts on domain example.com. Two of these accounts will have read and write permissions on accessing directory Incoming located in folder /private/photoshare which does not exist on the domain and which will be created with this request packet. The third user created with the packet will have only read permission on accessing the same directory. Total size of files that the FTP users are allowed to upload will be limited to 100 Mbytes.
<packet version="1.4.2.0"> <ftp-user> <add> <name>photo1</name> <password>dkfje44Fwen</password> <home>/private/photoshare/Incoming</home> <create-non-existent>true</create-non-existent> <quota>104857600</quota> <permissions> <read>true</read> <write>true</write> </permissions> <domain-name>example.com</domain-name> </add> <add> <name>photo2</name> <password>jrtd30fH33</password> <home>/private/photoshare/Incoming</home> <quota>104857600</quota> <permissions> <read>true</read> <write>true</write> </permissions> <domain-name>example.com</domain-name> </add> <add>

Supported Operations <name>photo3</name> <password>J7chhend</password> <home>/private/photoshare/Incoming</home> <permissions> <read>true</read> <write>false</write> </permissions> <domain-name>example.com</domain-name> </add> </ftp-user> </packet>

565

Response Packet Structure


The add node of the output XML packet is structured as follows:

The result node is required. It wraps the response received from the server. Data type: FtpUserSimpleResultType (ftpuser.xsd). The status node is required. Specifies the execution status of the add operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the add operation fails. Data type: unsignedInt. The errtext node is optional. Is used to return the error message if the add operation fails. Data type: string. The id node is required if the operation succeeds. It returns the unique identifier of the FTP account created with the add operation. Data type: integer.

566

Supported Operations

Response Samples
Positive responses This packet is received after successful creation of FTP account to which ID 5 was assigned.
<packet version="1.4.2.0"> <ftp-user> <add> <result> <status>ok</status> <id>5</id> </result> </add> </ftp-user> </packet>

This packet is received after successful creation of three FTP accounts, to which IDs 7, 8 and 9 were assigned.
<packet version="1.4.2.0"> <ftp-user> <add> <result> <status>ok</status> <id>7</id> </result> </add> <add> <result> <status>ok</status> <id>8</id> </result> </add> <add> <result> <status>ok</status> <id>9</id> </result> </add> </ftp-user> </packet>

Supported Operations

567

Negative responses Response packet with such error is received from server if the request packet creating an account tried to create an account home directory in the root domain folder, which is prohibited by Plesk.
<packet version="1.4.2.0"> <ftp-user> <add> <result> <status>error</status> <errcode>1006</errcode> <errtext>Unable to create directory /Upload: Access denied</errtext> </result> </add> </ftp-user> </packet>

You will receive such response if the home node in request packet contains path to folder which does not exist on a domain, and no create-non-existent node is included to the request.
<packet version="1.4.2.0"> <ftp-user> <add> <result> <status>error</status> <errcode>1019</errcode> <errtext>Invalid path specified</errtext> </result> </add> </ftp-user> </packet>

Such response is received if the request packet tries to create FTP account on a domain where the maximum allowed number of FTP accounts already exists.
<packet version="1.4.2.0"> <ftp-user> <add> <result> <status>error</status> <errcode>1024</errcode> <errtext>FTP subaccounts limit is reached for this domain</errtext> </result> </add> </ftp-user> </packet>

568

Supported Operations

Retrieving Information On FTP Accounts


The get operation is used to retrieve the following FTP account settings: Name/ login Home directory Quota on using disk space Permissions for home directory ID of the domain on which FTP account exists

You can retrieve information on several FTP accounts in a single get operation by defining the filtering rule. Use the blank filter (<filter/>) parameter to get information about all FTP accounts on all domains for the user identified by credentials from HTTP header.

In this section:
Request Packet Structure.................................................................................. 568 Request Samples .............................................................................................. 569 Response Packet Structure ............................................................................... 571 Response Samples ........................................................................................... 573

Request Packet Structure


A request XML packet retrieving information on FTP account settings includes the get operation node:
<packet version=1.4.2.0> <ftp-user> <get> </get> </ftp-user> </packet>

The get node is presented by the FtpUserGetInputType complex type (ftpuser.xsd). The node has the following graphical representation:

The filter node is required. It indicates FTP accounts which settings are to be retrieved with the request packet. Data type: FtpUserFilterType (ftpuser.xsd). For information on this node structure, refer to Filtering Issues (see page 557).

Supported Operations

569

Remarks Within one get operation you can retrieve information on FTP accounts using only one filtering rule: account IDs, account names, domain IDs, or domain names. However, you can always use several different filtering rules within one packet by including to it several get nodes.

Request Samples
Retrieving information on a single FTP account This packet retrieves information on FTP account with ID 16.
<packet version="1.4.2.0"> <ftp-user> <get> <filter> <id>16</id> </filter> </get> </ftp-user> </packet>

This packet retrieves information on FTP account with name ftpuser1.


<packet version="1.4.2.0"> <ftp-user> <get> <filter> <name>ftpuser1</name> </filter> </get> </ftp-user> </packet>

Retrieving information on multiple FTP accounts This request packet is incorrect as both id and name nodes are nested in one filter node within one get operation.
<packet version=1.4.2.0> <ftp-user> <get> <filter> <name>some-ftp</name> <id>34</id> </filter> </get> </ftp-user> </packet>

570

Supported Operations

This packet retrieves information on FTP accounts with names photo1 and photo3, and on all FTP accounts existing on domain with ID 34.
<packet version=1.4.2.0> <ftp-user> <get> <filter> <name>photo1</name> <name>photo3</name> </filter> </get> <get> <filter> <domain-id>34</domain-id> </filter> </get> </ftp-user> </packet>

This packet retrieves information on all FTP accounts existing on domains called one.example.com and two.example.com.
<packet version=1.4.2.0> <ftp-user> <get> <filter> <domain-name>one.example.com</domain-name> <domain-name>two.example.com</domain-name> </filter> </get> </ftp-user> </packet>

This packet retrieves information on all FTP accounts existing on all domains created in Plesk if it is sent with Plesk Administrator credentials in the packet HTTP headers, or on all domains belonging to a Plesk client whose credentials are specified in the HTTP headers.
<packet version="1.4.2.0"> <ftp-user> <get> <filter/> </get> </ftp-user> </packet>

Supported Operations

571

Response Packet Structure


The get node of the output XML packet is structured as follows:

The result node is required. It wraps the response received from the server. Data type: FtpUserGetResultType (ftpuser.xsd). The status node is required. It specifies the execution status of the get operation. Data type: result_status. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get operation fails. Data type: string. The filter-id node is optional. It is required if the get operation succeeds. It returns the filtering rule. For more information, refer to the Filtering Issues (see page 559) section. Data type: anySimple. The id node is optional. It is required if the get operation succeeds. It returns the unique identifier of the FTP account which settings are retrieved in the response packet. Data type: integer.

572

Supported Operations

The name node is optional. It is required if the get operation succeeds. It specifies the name under which the FTP account is known in Plesk, and the account login. Data type: string.

The home node is optional. It is required if the get operation succeeds. It specifies the home directory of the FTP account, i.e., the directory access to which is granted for the account user. Data type: string.

The quota node is optional. It is required if the get operation succeeds. It specifies the maximum total size of files and folders (in bytes) that the FTP account user can create in or upload to the home directory. Data type: integer.

The permissions node is optional. It is required if the get operation succeeds. It specifies the FTP account permissions for home directory. For more information, refer to section FTP Account Permissions (see page 556). Data type: FtpUserPermissions. The domain-id node is optional. It is required if the get operation succeeds. It specifies the ID of the domain on which the FTP account exists. Data type: integer.

Remarks In case when a domain was specified as filtering rule in a request packet, and there are no FTP accounts existing on that domain, response packet does not contain the name, home, quota, permissions and domain-id nodes.

Supported Operations

573

Response Samples
Positive responses This packet retrieved information on FTP account created with default home directory and only required settings specified within the node. For details on adding accounts, refer to the Creating FTP Accounts (see page 560) section.
<packet version="1.4.2.0"> <ftp-user> <get> <result> <status>ok</status> <filter-id>16</filter-id> <id>16</id> <name>jenny</name> <home></home> <quota>-1</quota> <permissions> <read>false</read> <write>false</write> </permissions> <domain-id>1</domain-id> </result> </get> </ftp-user> </packet>

This packet retrieved information on two FTP accounts filtered by names, and information on FTP accounts existing on a domain with ID 34. The last get node in this response contains only status and filter-id nodes, which means that no FTP accounts exist on the specified domain.
<packet version="1.4.2.0"> <ftp-user> <get> <result> <status>ok</status> <filter-id>photo1</filter-id> <id>7</id> <name>photo1</name> <home>/private/photoshare/Incoming</home> <quota>104857600</quota> <permissions> <read>true</read> <write>true</write> </permissions> <domain-id>2</domain-id> </result> <result> <status>ok</status> <filter-id>photo3</filter-id> <id>9</id> <name>photo3</name> <home>/private/photoshare/Incoming</home> <quota>0</quota> <permissions>

574

Supported Operations <read>true</read> <write>false</write> </permissions> <domain-id>2</domain-id> </result> </get> <get> <result> <status>ok</status> <filter-id>34</filter-id> </result> </get> </ftp-user> </packet>

Negative Responses This packet returned error because the request packet sent to the server intended to retrieve information on FTP account with ID 88 which does not exist.
<packet version="1.4.2.0"> <ftp-user> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>ftp-user does not exist</errtext> <filter-id>88</filter-id> <id>88</id> </result> </get> </ftp-user> </packet>

This packet returned error because the request packet sent to server by Plesk client intended to retrieve information on FTP account which exists on a domain belonging to another Plesk client.
<packet version="1.4.2.0"> <ftp-user> <get> <result> <status>error</status> <errcode>1006</errcode> <errtext>Permission denied.</errtext> <filter-id>ivanov.ru</filter-id> </result> </get> </ftp-user> </packet>

Supported Operations

575

Changing FTP Account Settings

The set operation is used to change settings of additional FTP accounts existing in Plesk database. You can change settings of particular FTP accounts, or of all FTP accounts existing on particular domains or in the whole Plesk database, depending on what Plesk user credentials are specified in HTML headers of request packet.

Note: Plesk clients can change quota on disk space used by home directory only if they are granted the Hard disk quota assignment permission (see page 74).

In this section:
Request Packet Structure.................................................................................. 575 Request Samples .............................................................................................. 577 Response Packet Structure ............................................................................... 580 Response Samples ........................................................................................... 581

Request Packet Structure


A request XML packet changing FTP account settings in the Plesk database includes the set operation node:
<packet version="1.4.2.0"> <ftp-user> <set> ... </set> </ftp-user> </packet>

576

Supported Operations

The set node is presented with the FtpUserSetInputType complex type (ftpuser.xsd), its graphical representation is as follows:

The filter node is required. It indicates FTP accounts which settings are to be updated with the information specified in values node. Data type: FtpUserFilterType (ftpuser.xsd). For information on this node structure, refer to Filtering Issues (see page 557). The values node is required. It wraps a collection of settings that will be applied to the accounts specified with filter node. Data type: FtpUserSetType (ftpuser.xsd). The name node is optional. It specifies the new name under which the FTP account will be known in Plesk, and the new account login. Data type: string. The password node is optional. It specifies the new FTP account password. Data type: string. The home node is optional. It specifies the new home directory of the account, i.e., the directory access to which is granted for the account user. Data type: string. The create-non-existent node is optional. It specifies if the new home directory should be created or not. This node with value true is required if new home directory defined with the home node does not exist. Data type: boolean. The quota node is optional. It specifies the maximum total size of files and folders (in bytes) that the FTP account user can create in or upload to the home directory. Data type: integer. The permissions node is optional. It specifies the FTP account permissions for home directory. For more information, refer to section FTP Account Permissions (see page 556). Data type: FtpUserPermissions.

Supported Operations

577

Remarks 1. The home node should contain a full path to FTP account home directory starting with root domain directory. For example: /httpdocs/billy/pub. If the home node is left blank (<home/>), then home directory for FTP account will be set to default one, which is the domain root directory. 2. Creating new folders in domain root directory is prohibited by Plesk. Therefore, it is impossible to make some /Global_Upload folder a home directory for an account. Do not include to your packets lines like
<home>/Global_Upload</home> <create-non-existent>true</create-non-existent>

3. To change FTP account quota to unlimited, specify value "-1" in the quota node:
<quota>-1</quota>

4. With one packet, you can change settings of as many different FTP accounts with different filtering rules as you want. To do so, use the required number of add nodes in the packet.

Request Samples
Changing settings of a single FTP account This packet sets up new password for FTP account with name "ftpuser2".
<packet version="1.4.2.0"> <ftp-user> <set> <filter> <name>ftpuser2</name> </filter> <values> <password>jkRR67hVBB</password> </values> </set> </ftp-user> </packet>

578

Supported Operations

This packet updates settings of FTP account with ID 46: It creates new account home directory /httpdocs/Pub and allows read and write permissions.
<packet version="1.4.2.0"> <ftp-user> <set> <filter> <id>46</id> </filter> <values> <home>/httpdocs/Pub</home> <create-non-existent>true</create-non-existent> <permissions> <read>true</read> <write>true</write> </permissions> </values> </set> </ftp-user> </packet>

Changing settings of multiple FTP accounts This packet is incorrect as it intends to give the same new name to all FTP accounts existing on domain with ID 85.
<packet version="1.4.2.0"> <ftp-user> <set> <filter> <domain-id>85</domain-id> </filter> <values> <name>ftp-doe1</name> </values> </set> </ftp-user> </packet>

This packet sets 10-Mbytes quota for all FTP accounts existing on domain example.com.
<packet version="1.4.2.0"> <ftp-user> <set> <filter> <domain-name>example.com</domain-name> </filter> <values> <quota>10485760</quota> </values> </set> </ftp-user> </packet>

Supported Operations

579

This packet allows read access and denies write access to all FTP accounts that can be managed by Plesk user defined in HTTP headers of the packet.
<packet version="1.4.2.0"> <ftp-user> <set> <filter/> <values> <permissions> <read>true</read> <write>false</write> </permissions> </values> </set> </ftp-user> </packet>

580

Supported Operations

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response received from the server. Data type: resultFilterType (ftpuser.xsd). The status node is required. Specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the set operation fails. Data type: unsignedInt. The errtext node is optional. Is used to return the error message if the set operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule. For more information, refer to the Filtering Issues (see page 559) section. The id node is required if the operation succeeds. It returns the unique identifier of the FTP account which settings were modified with add operation in request packet. Data type: integer.

Supported Operations

581

Response Samples
Positive responses This packet has been received after successful changing settings of FTP account called ftpuser2.
<packet version="1.4.2.0"> <ftp-user> <set> <result> <status>ok</status> <filter-id>ftpuser2</filter-id> <id>6</id> </result> </set> </ftp-user> </packet>

This packet has been received after successful changing settings of FTP accounts existing on domain example.com.
<packet version="1.4.2.0"> <ftp-user> <set> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>16</id> </result> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>25</id> </result> </set> </ftp-user> </packet>

Negative responses Packet with such error is received if the request packet intended to change settings of FTP account which does not exist in Plesk.
<packet version="1.4.2.0"> <ftp-user> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>ftp-user does not exist</errtext> <filter-id>666</filter-id> <id>666</id> </result> </set> </ftp-user></packet>

582

Supported Operations

Such packet is received if the request packet intended to set the same new name for all FTP accounts existing on one domain. The first result node contains info on successful renaming of FTP account with ID 316, the following result nodes contain the same error 1007.
<packet version="1.4.2.0"> <ftp-user> <set> <result> <status>ok</status> <filter-id>87</filter-id> <id>316</id> </result> <result> <status>error</status> <errcode>1007</errcode> <errtext>User ftp-doe7 already exists.</errtext> <filter-id>87</filter-id> <id>317</id> </result> <result> <status>error</status> <errcode>1007</errcode> <errtext>User ftp-doe7 already exists.</errtext> <filter-id>87</filter-id> <id>318</id> </result> </set> </ftp-user> </packet>

Deleting FTP Accounts


Use the del operation to remove FTP accounts from Plesk database. You can use this operation for deleting particular FTP accounts defined by name or ID, for deleting all FTP accounts existing on particular domains, also defined by name or ID, or for deleting all FTP accounts existing on all domains you can manage. In the last case, Plesk Administrator deletes all additional FTP accounts created on the whole Plesk server, Plesk client, in turn, deletes all additional FTP accounts created on his domains.

In this section:
Request Packet Structure.................................................................................. 583 Request Samples .............................................................................................. 583 Response Packet Structure ............................................................................... 585 Response Samples ........................................................................................... 586

Supported Operations

583

Request Packet Structure


A request XML packet deleting FTP account includes the del operation node:
<packet version=1.4.2.0> <ftp-user> <del> </del> </ftp-user> </packet>

The del node is presented by the FtpUserDelInputType complex type (ftpuser.xsd). The node has the following graphical representation:

The filter node is required. It indicates which FTP accounts are to be deleted with the request packet. Data type: FtpUserFilterType (ftpuser.xsd). For information on this node structure, refer to Filtering Issues (see page 557).

Remarks With one packet, you can delete as many different FTP accounts with different filtering rules as you want. To do so, use the required number of del nodes in the packet.

Request Samples
Deleting single FTP account This packet deletes FTP account with name photo4.
<packet version="1.4.2.0"> <ftp-user> <del> <filter> <name>photo4</name> </filter> </del> </ftp-user> </packet>

584

Supported Operations

This packet deletes FTP account with ID 44.


<packet version="1.4.2.0"> <ftp-user> <del> <filter> <id>44</id> </filter> </del> </ftp-user> </packet>

Deleting multiple FTP accounts This packet deletes FTP accounts with names ftpuser2, photo6.
<packet version="1.4.2.0"> <ftp-user> <del> <filter> <name>ftpuser2</name> <name>photo6</name> </filter> </del> </ftp-user> </packet>

This packet deletes all FTP accounts existing on domain example.com.


<packet version="1.4.2.0"> <ftp-user> <del> <filter> <domain-name>example.com</domain-name> </filter> </del> </ftp-user> </packet>

This packet removes all FTP accounts that can be managed by Plesk user defined in HTTP headers of the packet.
<packet version="1.4.2.0"> <ftp-user> <del> <filter/> </del> </ftp-user> </packet>

Supported Operations

585

Response Packet Structure


The del node of the output XML packet is structured as follows:

The result node is required. It wraps the response received from the server. Data type: resultFilterType (ftpuser.xsd). The status node is required. It specifies the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the del operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the del operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule. For more information, refer to the Filtering Issues (see page 559) section. Data type: anySimple. The id node is optional. It returns the unique identifier of the FTP account that has been deleted with the request packet. Data type: integer.

586

Supported Operations

Response Samples
Positive responses This packet has been received after successful deletion of FTP account called photo4, which had ID 15.
<packet version="1.4.2.0"> <ftp-user> <del> <result> <status>ok</status> <filter-id>photo4</filter-id> <id>15</id> </result> </del> </ftp-user> </packet>

This packet has been received after successful deletion of all FTP accounts that existed on domain doe3.com: These were FTP accounts with IDs 28 and 29.
<packet version="1.4.2.0"> <ftp-user> <del> <result> <status>ok</status> <filter-id>doe3.com</filter-id> <id>28</id> </result> <result> <status>ok</status> <filter-id>doe3.com</filter-id> <id>29</id> </result> </del> </ftp-user> </packet>

Such packet is received if the request packet intends to delete all FTP accounts from a domain where no FTP accounts exist. In this case it is domain example.com.
<packet version="1.4.2.0"> <ftp-user> <del> <result> <status>ok</status> <filter-id>example.com</filter-id> </result> </del> </ftp-user> </packet>

Supported Operations

587

Negative responses Negative response received from server can look as follows:
<packet version="1.4.2.0"> <ftp-user> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>ftp-user does not exist</errtext> <filter-id>photo4</filter-id> </result> </del> </ftp-user> </packet>

Managing IP Addresses
Operator: <ip> XML Schema: ip_input.xsd, ip_output.xsd Plesk version: all versions API RPC version: all versions Plesk user: Plesk Administrator Description The ip operator is used to manage IP addresses available on Plesk server. In Plesk, IP addresses can be shared or exclusive. Exclusive IP address can be assigned to a single customer, while shared IP address can be shared among several customer accounts. SSL protection with authentic digital certificates and Anonymous FTP services are available only to domains hosted on exclusive IP addresses. Supported operations

588

Supported Operations

ADD (see page 588) adds an IP address to Plesk server as shared or exclusive, specifying a netmask and server network interface GET (see page 592) retrieves the list of IP addresses available on the server SET (see page 595) updates properties for IP addresses available on the server DEL (see page 600) removes an IP address from Plesk server

In this section:
Adding IP Address............................................................................................. 588 Retrieving IP addresses .................................................................................... 592 Changing Type .................................................................................................. 595 Removing IP...................................................................................................... 600

Adding IP Address
Use the add operation to add IP address to Plesk server. Note: In Plesk powered by Virtuozzo, if the specified IP is not in VPS (Virtual Private Server) pool, the attempt to add it to Plesk database will result in error.

In this section:
Request Packet Structure.................................................................................. 588 Request Samples .............................................................................................. 589 Response Packet Structure ............................................................................... 590 Response Samples ........................................................................................... 591

Request Packet Structure


A request XML packet adding IP address to Plesk server includes the add operation node:
<packet version="1.4.2.0"> <ip> <add> </add> </ip> </packet>

Supported Operations

589

Graphical representation of the add node is as follows:

The ip_address node is required. It specifies the IP address you want to add to Plesk database. Data type: ip_address (common.xsd). The netmask node is required. It specifies the netmask of the network. Data type: ip_address (common.xsd). The type node is required. It specifies the type of IP address. Data type: string. Allowed values: shared | exclusive. The interface node is required. It specifies the network interface name. Data type: string.

Remarks You can add multiple IP addresses in a single packet. Add as many add operations as the number of IPs you want to add.
<ip> <add> </add> ... <add> </add> </ip>

Request Samples
Adding a single IP address This packet adds a single shared IP address to Plesk server.
<packet version ="1.4.2.0"> <ip> <add> <ip_address>192.0.2.18</ip_address> <netmask>255.255.255.0</netmask> <type>shared</type> <interface>Network Connection</interface> </add> </ip> </packet>

590

Supported Operations

Adding multiple IP addresses This packet adds two exclusive IP addresses to Plesk server.
<packet version ="1.4.2.0"> <ip> <add> <ip_address>192.0.2.17</ip_address> <netmask>255.255.255.0</netmask> <type>exclusive</type> <interface>Network Connection</interface> </add> <add> <ip_address>192.0.2.18</ip_address> <netmask>255.255.255.0</netmask> <type>exclusive</type> <interface>Network Connection</interface> </add> </ip> </packet>

Response Packet Structure


The add node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add operation fails. Data type: string. The id_address node is optional. If the add operation succeeds, it returns the IP address added to Plesk database. Data type: ip_address (common.xsd).

Supported Operations

591

Response Samples
Adding a single IP address This request packet adds a single shared IP address to Plesk server.
<packet version ="1.4.2.0"> <ip> <add> <ip_address>192.0.2.18</ip_address> <netmask>255.255.255.0</netmask> <type>shared</type> <interface>Network Connection</interface> </add> </ip> </packet>

The positive response from the server looks as follows:


<packet version ="1.4.2.0"> <ip> <add> <result> <status>ok</status> <ip_address>192.0.2.18</ip_address> </result> </add> </ip> </packet>

If the IP address is already in Plesk database, the response is as follows:


<packet version ="1.4.2.0"> <ip> <add> <result> <status>error</status> <errcode>1013</errcode> <errtext>IP address was already added on the server</errtext> </result> </add> </ip> </packet>

592

Supported Operations

Adding multiple IP addresses This request packet adds two exclusive IP addresses to Plesk server.
<packet version ="1.4.2.0"> <ip> <add> <ip_address>192.0.2.17</ip_address> <netmask>255.255.255.0</netmask> <type>exclusive</type> <interface>Network Connection</interface> </add> <add> <ip_address>192.0.2.16</ip_address> <netmask>255.255.255.0</netmask> <type>exclusive</type> <interface>Network Connection</interface> </add> </ip> </packet>

A possible response from the server can look as follows:


<packet version ="1.4.2.0"> <ip> <add> <result> <status>ok</status> <ip_address>192.0.2.17</ip_address> </result> </add> <add> <result> <status>ok</status> <ip_address>192.0.2.16</ip_address> </result> </add> </ip> </packet>

Supported Operations

593

Retrieving IP addresses
Use the get operation to retrieve all IP addresses from Plesk server database.

In this section:
Request Packet ................................................................................................. 593 Response Packet Structure ............................................................................... 593 Response Samples ........................................................................................... 595

Request Packet
A request XML packet retrieving IP addresses from Plesk database includes the get operation node:
<packet version="1.4.2.0"> <ip> <get/> </ip> </packet>

The get node graphical representation is as follows:

Request packet sample The packet retrieving IP addresses from Plesk database looks as follows:
<packet version="1.4.2.0"> <ip> <get/> </ip> </packet>

594

Supported Operations

Response Packet Structure


The get node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. The addresses node is optional. If the get operation succeeds, it returns the following data:

The ip_info node is required. It wraps the IP address info. The ip_address node is required. Specifies the IP address in Plesk database. Data type: ip_address (common.xsd). The netmask node is required. It specifies the netmask of the network. Data type: ip_address (common.xsd). The type node is required. It specifies the type of IP address. Data type: string. Allowed values: shared | exclusive. The interface node is required. It specifies the server network interface name. Data type: string.

Supported Operations

595

The default node is optional. It specifies if the IP address is default for a domain. It specifies if any domain is shown when you type the IP address in browser. Data type: none.

Note: the default node is supported starting with API RPC protocol v.1.4.2.0. The ip_info node is supported starting with 1.3.5.1 version of the protocol. Use the ip node instead of ip_info node in previous versions of the protocol.

Response Samples
The request packet looks as follows:
<packet version="1.4.2.0"> <ip> <get/> </ip> </packet>

A response packet can look as follows:


<packet version="1.4.2.0"> <ip> <get> <result> <status>ok</status> <addresses> <ip_info> <ip_address>10.58.49.221</ip_address> <netmask>255.255.0.0</netmask> <type>exclusive</type> <interface>eth0</interface> </ip_info> </addresses> </result> </get> </ip> </packet>

596

Supported Operations

Changing Type
Use the set operation to change IP address type. Note: You cannot change type of IP address from shared to exclusive if it is assigned to two or more clients.

In this section:
Request Packet Structure.................................................................................. 597 Request Samples .............................................................................................. 598 Response Packet Structure ............................................................................... 598 Response Samples ........................................................................................... 599

Supported Operations

597

Request Packet Structure


A request XML packet changing the IP address type includes the set operation node:
<packet version="1.4.2.0"> <ip> <set> </set> </ip> </packet>

The set node graphical representation is as follows:

The filter node is required. Specifies the filtering rule. Data type: ipFilterType (ip_input.xsd) The ip_address node is required. Specifies the IP address in Plesk database. Data type: ip_address (common.xsd). The type node is required. It specifies the type of IP address. Data type: string. Allowed values: shared | exclusive.

Remarks You can change type of multiple IP addresses in a single packet. Add as many ip_address operations as the number of IP addresses, the type of which is to be changed.
<filter> <ip_address>...</ip_address> ... <ip_address>...</ip_address> </filter>

598

Supported Operations

Request Samples
Changing type of a single IP address This packet changes the type of 192.0.2.1 IP address to exclusive.
<packet version="1.4.2.0"> <ip> <set> <filter> <ip_address>192.0.2.1</ip_address> </filter> <type>exclusive</type> </set> </ip> </packet>

Changing type of multiple IP addresses This packet changes the type of 192.0.2.10 and 192.0.2.12 IP addresses to exclusive.
<packet version="1.4.2.0"> <ip> <set> <filter> <ip_address>192.0.2.10</ip_address> <ip_address>192.0.2.12</ip_address> </filter> <type>exclusive</type> </set> </ip> </packet>

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).

Supported Operations

599

The status node is required. It specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set operation fails. Data type: string. The id_address node is optional. It returns the IP address which status is changed. Data type: ip_address (common.xsd).

Response Samples
Changing type of a single IP address This request packet changes the type of 192.0.2.1 IP address to exclusive.
<packet version="1.4.2.0"> <ip> <set> <filter> <ip_address>192.0.2.1</ip_address> </filter> <type>exclusive</type> </set> </ip> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <ip> <set> <result> <status>ok</status> <ip_address>192.0.2.1</ip_address> </result> </set> </ip> </packet>

If the IP was assigned to multiple customers, the response looks as follows:


<packet version="1.4.2.0"> <ip> <set> <result> <status>error</status> <errcode>1019</errcode> <errcode>General set IP error.</errcode> <ip_address>192.0.2.1</ip_address> </result> </set> </ip> </packet>

600

Supported Operations

Changing type of multiple IP addresses This packet changes the type of 192.0.2.10 and 192.0.2.12 IP addresses to exclusive.
<packet version="1.4.2.0"> <ip> <set> <filter> <ip_address>192.0.2.10</ip_address> <ip_address>192.0.2.12</ip_address> </filter> <type>exclusive</type> </set> </ip> </packet>

If the second IP address was not found, the response from the server looks as follows:
<packet version="1.4.2.0"> <ip> <set> <result> <status>ok</status> <ip_address>192.0.2.10</ip_address> </result> <result> <status>error</status> <errcode>1013</errcode> <errcode>ip does not exist.</errcode> <ip_address>192.0.2.12</ip_address> </result> </set> </ip> </packet>

Removing IP
Use the del operation to remove the IP address from Plesk database. You cannot remove the IP of the computer (defined by network configuration), where Plesk server is located. You also cannot remove the IP address if one or more domains are hosted on this IP or forwarded from this IP. Note: You cannot remove an IP address from IP pool of a reseller who shares this IP with Plesk clients.

In this section:
Request Packet Structure.................................................................................. 601 Request Samples .............................................................................................. 601 Response Packet Structure ............................................................................... 602 Response Samples ........................................................................................... 603

Supported Operations

601

Request Packet Structure


A request XML packet removing the IP address from Plesk database includes the del operation node:
<packet version="1.4.2.0"> <ip> <del> </del> </ip> </packet>

The del node graphical representation is as follows:

The filter node is required. Specifies the filtering rule. Data type: ipFilterType (ip_input.xsd). The ip_address node is required. Specifies the IP address in Plesk database. Data type: ip_address (common.xsd).

Remarks You can remove multiple IP addresses in a single packet. Add as many ip_address operations as the number of IP addresses you want to remove.
<filter> <ip_address>...</ip_address> ... <ip_address>...</ip_address> </filter>

Request Samples
Removing a single IP address This packet removers 192.0.2.1 IP address from Plesk database.
<packet version="1.4.2.0"> <ip> <del> <filter> <ip_address>192.0.2.1</ip_address> </filter> </del> </ip> </packet>

602

Supported Operations

Removing multiple IP addresses This packet removes 192.0.2.10 and 192.0.2.12 IP addresses.
<packet version="1.4.2.0"> <ip> <del> <filter> <ip_address>192.0.2.10</ip_address> <ip_address>192.0.2.12</ip_address> </filter> </del> </ip> </packet>

Response Packet Structure


The del node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the del operation fails. Data type: integer. The errtext node is optional. It returns the error message if the del operation fails. Data type: string. The id_address node is optional. It returns the removed IP address. Data type: ip_address (common.xsd).

Supported Operations

603

Response Samples
Removing a single IP address This request packet removers 192.0.2.1 IP address from Plesk database.
<packet version="1.4.2.0"> <ip> <del> <filter> <ip_address>192.0.2.1</ip_address> </filter> </del> </ip> </packet>

If it was Plesk server IP address, or this IP is used by hosting or forwarding services, the response from the server looks as follows:
<packet version="1.4.2.0"> <ip> <del> <result> <status>error</status> <errcode>1002</errcode> <errtext>Error: IP address 192.0.2.1 is used for hosting or forwarding. </errtext> </result> </del> </ip> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <ip> <del> <result> <status>ok</status> <ip_address>192.0.2.1</ip_address> </result> </del> </ip> </packet>

604

Supported Operations

Removing multiple IP addresses This request packet removes 192.0.2.1 and 192.0.2.2 IP addresses.
<packet version="1.4.2.0"> <ip> <del> <filter> <ip_address>192.0.2.1</ip_address> <ip_address>192.0.2.2</ip_address> </filter> </del> </ip> </packet>

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <ip> <del> <result> <status>error</status> <errcode>1002</errcode> <errtext>Error: IP address 192.0.2.1 is used for hosting or forwarding. </errtext> </result> <result> <status>error</status> <errcode>1002</errcode> <errtext>Error: IP address 192.0.2.2 is used for hosting or forwarding. </errtext> </result> </del> </ip> </packet>

Supported Operations

605

Managing Locales
Operator: <locale> XML Schema: locale.xsd Plesk version: 8.1.1 API RPC version: 1.5.0.0 Plesk user: Plesk Administrator Description A subset of Plesk user's environment adjusted to a particular language is called locale. On the implementation level, a particular locale is represented by the corresponding language pack (LP). Language pack is an installable file containing resource files. The files are associative arrays structured like "key => value". The locale operator is used to manage LP's and to localize messages wrapped in object descriptors. For information on descriptors, refer to the Descriptors Overview section of the Programming Guide. Supported operations

GET (on page 607) retrieves info on LP's installed on Plesk server INSTALL (on page 613) installs a specified LP to Plesk server GET-MESSAGE (on page 617) retrieves the message specified by a key from resource files of LP REMOVE (on page 621) removes LP from the server ENABLE (on page 627) enables LP on the server DISABLE (on page 632) disables LP on the server

606

Supported Operations

In this section:
LP Names ......................................................................................................... 606 Filtering Issues .................................................................................................. 606 Retrieving List of LP's ........................................................................................ 607 Installing LP....................................................................................................... 613 Retrieving Localized Messages ......................................................................... 617 Removing LP..................................................................................................... 621 Enabling LP ....................................................................................................... 627 Disabling LP ...................................................................................................... 632 Locale Codes .................................................................................................... 637

LP Names
Plesk locale and language pack names follow the RFC 1766 standard in the format "<languagecode2>-<country/regioncode2>", where <languagecode2> is a lower-case two-letter code derived from ISO 639-1 and <country/regioncode2> is an upper-case two-letter code derived from ISO 3166. For example, U.S. English locale is named "enUS". To see list of locale names supported by Plesk, refer to the Appendix. Locale Code. (on page 637) section.

Filtering Issues
Filtering is the way the request XML packet indicates the object (a LP or several) to which the operation will be applied. The request XML packet filters LPs using a special filter node. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

In this section:
Filter for Language Packs.................................................................................. 606 filter-id ............................................................................................................... 607

Supported Operations

607

Filter for Language Packs


The filter for this operator is presented by type LocaleFilterType (locale.xsd) and structured as follows:

The id node is optional. It specifies name of a LP. For details on LP names, refer to the LP Names (on page 606) section. Data type: string.

Remarks The filter node can be left blank (<filter/>). In this case all LP's on the server will be matched. A single filter can specify multiple LP names. The filter that matches the US English and Taiwan Chinese LP's looks as follows:
<filter> <id>en-US</id> <id>zh-TW</id> </filter>

filter-id

If an operation in a request packet uses filters, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If LP name was set as a filter rule parameter, it is returned in the filter-id node of the response packet. It is done to trace the request parameters in case of error. Data type: anySimple.

608

Supported Operations

Retrieving List of LP's


Use the get operation in the following cases: To retrieve list of language packs installed on the server To retrieve detailed info on each LP

In this section:
Request Packet Structure ..................................................................................608 Request Samples ..............................................................................................609 Response Packet Structure ...............................................................................610 Response Samples ............................................................................................612

Request Packet Structure


A request XML packet retrieving info on LP's includes the get operation node:
<packet version="1.5.0.0"> <locale> <get> </get> </locale> </packet>

The get node is presented by type LocaleGetInput (locale.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: LocaleFilter (locale.xsd).

Supported Operations

609

Request Samples
Retrieving info on a single LP The following request packet retrieves info on US English LP:
<packet version="1.5.0.0"> <locale> <get> <filter> <id>en-US</id> </filter> </get> </locale> </packet>

Retrieving info on multiple LP's The following request packet retrieves info on US English and Russian LP's:
<packet version="1.5.0.0"> <locale> <get> <filter> <id>en-US</id> <id>ru-RU</id> </filter> </get> </locale> </packet>

The following request packet retrieves info on all LP's installed on the server:
<packet version="1.5.0.0"> <locale> <get> <filter/> </get> </locale> </packet>

610

Supported Operations

Response Packet Structure


The get node of the output XML packet is presented by type LocaleGetOutput (locale.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: extension of type LocaleResultType (locale.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the get operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter if the operation fails. For more information, refer to the Filtering Issues (on page 643) section. Data type:anySimpleType. The id node is optional. It holds name of the language pack matched by the filtering rule if the operation fails. Data type: string. The message node is optional. It does not return any value for this operation. Data type: string.

Note: In API RPC v.1.5.1.0 and later versions, the node is absent if the response packets. The info node is optional. It specifies LP settings. Data type: LocaleInfo (locale.xsd). If the info node is present in the response packet, the following nodes are required:

Supported Operations

611

The id node specifies the LP name. For details on language pack names, refer to the LP Names (on page 606) section. Data type: string. The lang node specifies the LP language. Data type: string. The country node specifies countries where this language is native. Data type: string. The used node specifies the number of users at all levels that use this language in their interface. Data type: integer. The enabled node specifies if this LP is available for users. Data type: boolean.

Remarks In API RPC v.1.5.0.0, the result node also contains the message node.

The message node is optional. It does not return any value for this operation. Data type: string.

612

Supported Operations

Response Samples
Retrieving info on a single LP The following request packet retrieves info on US English LP:
<packet version="1.5.0.0"> <locale> <get> <filter> <id>en-US</id> </filter> </get> </locale> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <locale> <get> <result> <status>ok</status> <info> <id>en-US</id> <lang>ENGLISH</lang> <country>United States</country> <used>17</used> <enabled>true</enabled> </info> </result> </get> </locale> </packet>

If the LP was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <locale> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>en-US</filter-id> <id>en-US</id> </result> </get> </locale> </packet>

Supported Operations

613

Retrieving info on multiple LP's The following request packet retrieves info on US English and Russian LP's:
<packet version="1.5.0.0"> <locale> <get> <filter> <id>en-US</id> <id>ru-RU</id> </filter> </get> </locale> </packet>

If US English LP was found, and Russian LP was not found on the server, the response is as follows:
<packet version="1.5.0.0"> <locale> <get> <result> <status>ok</status> <info> <id>en-US</id> <lang>ENGLISH</lang> <country>United States</country> <used>17</used> <enabled>true</enabled> </info> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>ru-RU</filter-id> <id>ru-RU</id> </result> </get> </locale> </packet>

614

Supported Operations

Installing LP
The install operation is used to install a specified language pack to Plesk server. Note: This operation is unavailable in Plesk for Windows.

In this section:
Request Packet Structure.................................................................................. 614 Request Samples .............................................................................................. 614 Response Packet Structure ............................................................................... 615 Response Samples ........................................................................................... 616

Request Packet Structure


A request XML packet installing LP includes the install operation node:
<packet version="1.5.0.0"> <locale> <install> </install> </locale> </packet>

The install node is presented by type LocaleInstallInput (locale.xsd), and its graphical representation is as follows:

The filename node is required. Specifies the LP package full name. This file should reside on the server. You can use the upload operator to upload files to the server. Data type: string.

Request Samples
The following request packet installs US English LP to the server:
<packet version="1.5.0.0"> <locale> <install> <filename>./tmp/en-RU.rpm</filename> </install> </locale> </packet>

Supported Operations

615

Response Packet Structure


The install node of the output XML packet is presented by type LocalInstallOutput (locale.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the install operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the install operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the install operation fails. Data type: string.

616

Supported Operations

Response Samples
The following request packet installs US English LP to the server:
<packet version="1.5.0.0"> <locale> <install> <filename>./tmp/en-RU.rpm</filename> </install> </locale> </packet>

The positive response from the server looks as follows:


<packet version="1.5.0.0"> <locale> <install> <result> <status>ok</status> </result> </install> </locale> </packet>

If the file was not found on the server, the response from the server looks as follows:
<packet version="1.5.0.0"> <locale> <install> <result> <status>error</status> <errcode>1013</errcode> <errtext>File not found</errtext> </result> </install> </locale> </packet>

If the request packet was sent to Plesk for Windows server, the response is as follows:
<packet version="1.5.0.0"> <locale> <install> <result> <status>error</status> <errcode>1017</errcode> <errtext>Feature not supported by Plesk API-RPC</errtext> </result> </install> </locale> </packet>

Supported Operations

617

Retrieving Localized Messages


Resource files of LP are associative arrays, structured like key => value. One key can be equal to different values depending on a locale name. For instance, hst_def__fp_admin_login key can be equal to "FrontPage Administrator's Login" in US English locale and to "Login administrateur FrontPage" in French locale. To retrieve a key value for a specified locale, use the get-message operation.

In this section:
Request Packet Structure.................................................................................. 617 Request Samples .............................................................................................. 618 Response Packet Structure ............................................................................... 619 Response Samples ........................................................................................... 620

Request Packet Structure


A request XML packet retrieving localized messages includes the get-message operation node:
<packet version="1.5.0.0"> <get-message> <install> </install> </get-message> </packet>

The get-message node is presented by type LocaleGetMessageInput (locale.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: LocaleGetMessageFilter (locale.xsd). The key node is required. It specifies the key name. Data type: string. The id node is required. It specifies the language pack name. For details, refer to the LP Names (on page 606) section. Data type: string.

618

Supported Operations

Request Samples
Retrieving value for a single key The following request packet retrieves value for the hst_def__fp_admin_login key in US English locale:
<packet version="1.5.0.0"> <locale> <get-message> <filter> <key>hst_def__fp_admin_login</key> </filter> <id>en-US</id> </get-message> </locale> </packet>

Retrieving value for multiple keys The following request packet retrieves values for the hst_def__fp_admin_login and hst_def__fp_admin_passwd keys in French locale:
<packet version="1.5.0.0"> <locale> <get-message> <filter> <key>hst_def__fp_admin_login</key> <key>hst_def__fp_admin_passwd</key> </filter> <id>fr-FR</id> </get-message> </locale> </packet>

The following request packet retrieves values for the hst_def__fp_admin_login and hst_def__fp_admin_passwd keys in French and US English locales:
<packet version="1.5.0.0"> <locale> <get-message> <filter> <key>hst_def__fp_admin_login</key> <key>hst_def__fp_admin_passwd</key> </filter> <id>fr-FR</id> </get-message> <get-message> <filter> <key>hst_def__fp_admin_login</key> <key>hst_def__fp_admin_passwd</key> </filter> <id>en-US</id> </get-message> </locale> </packet>

Supported Operations

619

Response Packet Structure


The get-message node of the output XML packet is presented by type LocaleGetMessageOutput (locale.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: LocaleMessageResultType (locale.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple. The id node is optional. It holds name of the language pack matched by the filtering rule. Data type: string. The message node is optional. It holds value of the key received from the request packet. Data type: string.

620

Supported Operations

Response Samples
Retrieving value for a single key The following request packet retrieves value for the hst_def__fp_admin_login key in US English locale:
<packet version="1.5.0.0"> <locale> <get-message> <filter> <key>hst_def__fp_admin_login</key> </filter> <id>en-US</id> </get-message> </locale> </packet>

The positive response from the server looks as follows:


<packet version="1.5.0.0"> <locale> <get-message> <result> <status>ok</status> <filter-id>hst_def__fp_admin_login</filter-id> <id>en-US</id> <message>FrontPage Administrator's Login</message> </result> </get-message> </locale> </packet>

If the key was not found, the response is as follows:


<packet version="1.5.0.0"> <locale> <get-message> <result> <status>error</status> <errcode>1013</errcode> <errtext>Key does not exist</errtext> <filter-id>hst_def__fp_admin_login</filter-id> <id>fr-FR</id> </result> </get-message> </locale> </packet>

Supported Operations

621

Retrieving value for multiple keys

The following request packet retrieves values for the hst_def__fp_admin_login and hst_def__fp_admin_passwd keys in French locale:
<packet version="1.5.0.0"> <locale> <get-message> <filter> <key>hst_def__fp_admin_login</key> <key>hst_def__fp_admin_passwd</key> </filter> <id>fr-FR</id> </get-message> </locale> </packet>

A possible response from the server can look as follows:


<packet version="1.5.0.0"> <locale> <get-message> <result> <status>ok</status> <filter-id>hst_def__fp_admin_login</filter-id> <id>en-US</id> <message>FrontPage Administrator's Login</message> </result> <result> <status>ok</status> <filter-id>hst_def__fp_admin_passwd</filter-id> <id>fr-FR</id> <message>Mot de passe administrateur de FrontPage</message> </result> </get-message> </locale> </packet>

622

Supported Operations

Removing LP
The remove operation is used to remove a specified language pack from the server. Note: You cannot remove the default language pack.

In this section:
Request Packet Structure.................................................................................. 622 Request Samples .............................................................................................. 623 Response Packet Structure ............................................................................... 624 Response Samples ........................................................................................... 625

Request Packet Structure


A request XML packet removing LP's includes the remove operation node:
<packet version="1.5.0.0"> <locale> <remove> </remove> </locale> </packet>

The remove node is presented by type LocaleRemoveInput (locale.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: LocaleFilter (locale.xsd).

Supported Operations

623

Request Samples
Removing a single LP

The following request packet removes French LP:


<packet version="1.5.0.0"> <locale> <remove> <filter> <id>fr-FR</id> </filter> </remove> </locale> </packet>

Removing multiple LP's The following request packet removes German and French LP's:
<packet version="1.5.0.0"> <locale> <remove> <filter> <id>de-DE</id> <id>fr-FR</id> </filter> </remove> </locale> </packet>

The following request packet removers all LP's installed on the server (except for enUS):
<packet version="1.5.0.0"> <locale> <remove> <filter/> </remove> </locale> </packet>

624

Supported Operations

Response Packet Structure


The remove node of the output XML packet is presented by type LocaleRemoveOutput (locale.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: LocaleResultType (locale.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple. The id node is optional. It holds name of the language pack matched by the filtering rule. Data type: string.

Supported Operations

625

Remarks In API RPC v.1.5.0.0, the result node also contains the message node.

The message node is optional. It does not return any value for this operation. Data type: string.

Response Samples
Removing a single LP The following request packet removes French LP:
<packet version="1.5.0.0"> <locale> <remove> <filter> <id>fr-FR</id> </filter> </remove> </locale> </packet>

The positive response from the server looks as follows:


<packet version="1.5.0.0"> <locale> <remove> <result> <status>ok</status> <filter-id>fr-FR</filter-id> <id>fr-FR</id> </result> </remove> </locale> </packet>

626

Supported Operations

If the LP was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <locale> <remove> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>fr-FR</filter-id> <id>fr-FR</id> </result> </remove> </locale> </packet>

Removing multiple LP's The following request packet removes US English and Russian LP's:
<packet version="1.5.0.0"> <locale> <get> <filter> <id>en-US</id> <id>ru-RU</id> </filter> </get> </locale> </packet>

A possible response from the server can look as follows:


<packet version="1.5.0.0"> <locale> <remove> <result> <status>error</status> <errcode>1023</errcode> <errtext>Unable to remove Plesk base locale</errtext> <filter-id>en-US</filter-id> <id>en-US</id> </result> <result> <status>ok</status> <filter-id>ru-RU</filter-id> <id>ru-RU</id> </result> </remove> </locale> </packet>

Supported Operations

627

Enabling LP
The enable operation is used to enable LP on the server.

In this section:
Request Packet Structure.................................................................................. 627 Request Samples .............................................................................................. 628 Response Packet Structure ............................................................................... 629 Response Samples ........................................................................................... 630

Request Packet Structure


A request XML packet enabling LP's includes the enable operation node:
<packet version="1.5.0.0"> <locale> <enable> </enable> </locale> </packet>

The enable node is presented by type LocaleEnableInput (locale.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: LocaleFilter (locale.xsd).

628

Supported Operations

Request Samples
Enabling a single LP The following request packet enables French LP:
<packet version="1.5.0.0"> <locale> <enable> <filter> <id>fr-FR</id> </filter> </enable> </locale> </packet>

Enabling multiple LP's The following request packet enables German and French LP's:
<packet version="1.5.0.0"> <locale> <enable> <filter> <id>de-DE</id> <id>fr-FR</id> </filter> </enable> </locale> </packet>

The following request packet enables all LP's installed on the server:
<packet version="1.5.0.0"> <locale> <enable> <filter/> </enable> </locale> </packet>

Supported Operations

629

Response Packet Structure


The enable node of the output XML packet is presented by type LocaleEnableOutput (locale.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: LocaleResultType (locale.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple. The id node is optional. It holds name of the language pack matched by the filtering rule. Data type: string.

630

Supported Operations

Remarks In API RPC v.1.5.0.0, the result node also contains the message node.

The message node is optional. It does not return any value for this operation. Data type: string.

Response Samples
Enabling a single LP The following request packet enables French LP:
<packet version="1.5.0.0"> <locale> <enable> <filter> <id>fr-FR</id> </filter> </enable> </locale> </packet>

The positive response from the server looks as follows:


<packet version="1.5.0.0"> <locale> <enable> <result> <status>ok</status> <filter-id>fr-FR</filter-id> <id>fr-FR</id> </result> </enable> </locale> </packet>

Supported Operations

631

If the LP was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <locale> <enable> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>fr-FR</filter-id> <id>fr-FR</id> </result> </enable> </locale> </packet>

Enabling multiple LP's The following request packet enables French and Russian LP's:
<packet version="1.5.0.0"> <locale> <enable> <filter> <id>fr-FR</id> <id>ru-RU</id> </filter> </enable> </locale> </packet>

A possible response from the server can look as follows:


<packet version="1.5.0.0"> <locale> <enable> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>fr-FR</filter-id> <id>en-US</id> </result> <result> <status>ok</status> <filter-id>ru-RU</filter-id> <id>ru-RU</id> </result> </enable> </locale> </packet>

632

Supported Operations

Disabling LP
The disable operation is used to enable LP on the server. Note: You cannot disable the default language pack.

In this section:
Request Packet Structure.................................................................................. 632 Request Samples .............................................................................................. 633 Response Packet Structure ............................................................................... 634 Response Samples ........................................................................................... 635

Request Packet Structure


A request XML packet disabling LP's includes the disable operation node:
<packet version="1.5.0.0"> <locale> <disable> </disable> </locale> </packet>

The disable node is presented by type LocaleDisableInput (locale.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: LocaleFilter (locale.xsd).

Supported Operations

633

Request Samples
Disabling a single LP The following request packet disables French LP:
<packet version="1.5.0.0"> <locale> <disable> <filter> <id>fr-FR</id> </filter> </disable> </locale> </packet>

Disabling multiple LP's The following request packet disables German and French LP's:
<packet version="1.5.0.0"> <locale> <disable> <filter> <id>de-DE</id> <id>fr-FR</id> </filter> </disable> </locale> </packet>

The following request packet disables all LP's installed on the server:
<packet version="1.5.0.0"> <locale> <disable> <filter/> </disable> </locale> </packet>

634

Supported Operations

Response Packet Structure


The disable node of the output XML packet is presented by type LocaleDisableOutput (locale.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: LocaleResultType (locale.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is optional. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple. The id node is optional. It holds name of the language pack matched by the filtering rule. Data type: string.

Supported Operations

635

Remarks In API RPC v.1.5.0.0, the result node also contains the message node.

The message node is optional. It does not return any value for this operation. Data type: string.

Response Samples
Disabling a single LP The following request packet disables French LP:
<packet version="1.5.0.0"> <locale> <disable> <filter> <id>fr-FR</id> </filter> </disable> </locale> </packet>

The positive response from the server looks as follows:


<packet version="1.5.0.0"> <locale> <disable> <result> <status>ok</status> <filter-id>fr-FR</filter-id> <id>fr-FR</id> </result> </disable> </locale> </packet>

636

Supported Operations

If the LP was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <locale> <disable> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>fr-FR</filter-id> <id>fr-FR</id> </result> </disable> </locale> </packet>

Disabling multiple LP's The following request packet disables French and Russian LP's:
<packet version="1.5.0.0"> <locale> <disable> <filter> <id>fr-FR</id> <id>ru-RU</id> </filter> </disable> </locale> </packet>

A possible response from the server can look as follows:


<packet version="1.5.0.0"> <locale> <disable> <result> <status>error</status> <errcode>1013</errcode> <errtext>Locale does not exist</errtext> <filter-id>fr-FR</filter-id> <id>en-US</id> </result> <result> <status>ok</status> <filter-id>ru-RU</filter-id> <id>ru-RU</id> </result> </disable> </locale> </packet>

Supported Operations

637

Locale Codes
Language Country/Region
Afrikaans Afrikaans - South Africa Albanian Albanian - Albania Arabic Arabic - Algeria Arabic Bahrain Arabic Egypt Arabic Iraq Arabic Jordan Arabic Kuwait Arabic Lebanon Arabic Libya Arabic - Morocco Arabic - Oman Arabic - Qatar Arabic - Saudi Arabia Arabic - Syria Arabic - Tunisia Arabic - United Arab Emirates Arabic - Yemen Armenian Armenian - Armenia Azeri Azeri - Azerbaijan Basque Basque - Basque Belarusian Belarusian - Belarus Bulgarian Bulgarian - Bulgaria Catalan

Code
af af-ZA sq sq-AL ar ar-DZ ar-BH ar-EG ar-IQ ar-JO ar-KW ar-LB ar-LY ar-MA ar-OM ar-QA ar-SA ar-SY ar-TN ar-AE ar-YE hy hy-AM az az-AZ eu eu-ES be be-BY bg bg-BG ca

Language - Country/Region
Icelandic Icelandic - Iceland Indonesian Indonesian - Indonesia Italian Italian - Italy Italian - Switzerland Japanese Japanese - Japan Kannada Kannada - India Kazakh Kazakh - Kazakhstan Korean Korean - Korea Kyrgyz Kyrgyz - Kyrgyzstan Latvian Latvian - Latvia Lithuanian Lithuanian - Lithuania Macedonian Macedonian - Former Yugoslav Republic of Macedonia Malay Malay - Brunei Malay - Malaysia Marathi Marathi - India Mongolian Mongolian - Mongolia Norwegian Norwegian (Bokml) - Norway

Code
is is-IS id id-ID it it-IT it-CH ja ja-JP kn kn-IN kk kk-KZ ko ko-KR ky ky-KG lv lv-LV lt lt-LT mk mk-MK ms ms-BN ms-MY mr mr-IN mn mn-MN no nb-NO

638

Supported Operations

Language Country/Region
Catalan - Spain Chinese Chinese - Hong Kong SAR Chinese - Macao SAR Chinese - China (Simplified Chinese) Chinese - Singapore Chinese - Taiwan (Traditional Chinese) Croatian Croatian - Croatia Czech Czech - Czech Republic Danish Danish - Denmark Dutch Dutch - Belgium Dutch - The Netherlands English English - Australia English - Belize English - Canada English - Caribbean English - Ireland English - Jamaica English - New Zealand English - Philippines English - South Africa English - Trinidad and Tobago English - United Kingdom English - United States English - Zimbabwe Estonian Estonian - Estonia Faroese Faroese - Faroe Islands

Code
ca-ES zh zh-HK zh-MO zh-CN zh-SG zh-TW hr hr-HR cs cs-CZ da da-DK nl nl-BE nl-NL en en-AU en-BZ en-CA en-CB en-IE en-JM en-NZ en-PH en-ZA en-TT en-GB en-US en-ZW et et-EE fo fo-FO

Language - Country/Region
Norwegian (Nynorsk) - Norway Polish Polish - Poland Portuguese Portuguese - Brazil Portuguese - Portugal Punjabi Punjabi - India Romanian Romanian - Romania Russian Russian - Russia Sanskrit Sanskrit - India Serbian Serbian - Serbia Slovak Slovak - Slovakia Slovenian Slovenian - Slovenia Spanish Spanish - Argentina Spanish - Bolivia Spanish - Chile Spanish - Colombia Spanish - Costa Rica Spanish - Dominican Republic Spanish - Ecuador Spanish - El Salvador Spanish - Guatemala Spanish - Honduras Spanish - Mexico Spanish - Nicaragua Spanish - Panama

Code
nn-NO pl pl-PL pt pt-BR pt-PT pa pa-IN ro ro-RO ru ru-RU sa sa-IN sr sr-SP sk sk-SK sl sl-SI es es-AR es-BO es-CL es-CO es-CR es-DO es-EC es-SV es-GT es-HN es-MX es-NI es-PA

Supported Operations

639

Language Country/Region
Farsi Farsi - Iran Finnish Finnish - Finland French French - Belgium French - Canada French - France French - Luxembourg French - Monaco French - Switzerland Galician Galician - Galician Georgian Georgian - Georgia German German - Austria German - Germany German - Liechtenstein German - Luxembourg German - Switzerland Greek Greek - Greece Gujarati Gujarati - India Hebrew Hebrew - Israel Hindi Hindi - India Hungarian Hungarian - Hungary

Code
fa fa-IR fi fi-FI fr fr-BE fr-CA fr-FR fr-LU fr-MC fr-CH gl gl-ES ka ka-GE de de-AT de-DE de-LI de-LU de-CH el el-GR gu gu-IN he he-IL hi hi-IN hu hu-HU

Language - Country/Region
Spanish - Paraguay Spanish - Peru Spanish - Puerto Rico Spanish - Spain Spanish - Uruguay Spanish - Venezuela Swahili Swahili - Kenya Swedish Swedish - Finland Swedish - Sweden Tamil Tamil - India Tatar Tatar - Russia Telugu Telugu - India Thai Thai - Thailand Turkish Turkish - Turkey Ukrainian Ukrainian - Ukraine Urdu Urdu - Pakistan Uzbek Uzbek - Uzbekistan Vietnamese Vietnamese - Vietnam

Code
es-PY es-PE es-PR es-ES es-UY es-VE sw sw-KE sv sv-FI sv-SE ta ta-IN tt tt-RU te te-IN th th-TH tr tr-TR uk uk-UA ur ur-PK uz uz-UZ vi vi-VN

640

Supported Operations

Managing Log Rotation on Domain


Operator: <log-rotation> XML Schema: logrotation.xsd Plesk version: 8.1.1 API RPC version: 1.5.0.0 Plesk user: Plesk Administrator, Plesk client Description All connections to a domain and errors on the domain are registered in domain log files. These log files are analyzed by the statistical utilities running on the server. The log-rotation operator is used to manage raw and processed log files. In other words, logrotation represents Log Rotation service in Plesk.

In this section:
Log Rotation Settings ........................................................................................ 641 Filtering Issues .................................................................................................. 642 Changing Log Rotation Settings ........................................................................ 644 Retrieving Log Rotation Settings ....................................................................... 650 Enabling Log Rotation Service .......................................................................... 656 Disabling Log Rotation Service ......................................................................... 661 Checking Status of Log Rotation Service .......................................................... 667

Supported Operations

641

Supported operations

SET (on page 644) changes Log Rotation settings. GET (on page 650) retrieves Log Rotation settings. ENABLE (on page 656) enables Log Rotation service on a domain DISABLE (on page 661) disables Log Rotation service on a domain GET-STATUS (on page 667) retrieves status of Log Rotation service

Log Rotation Settings


The settings are defined by type LogRotationSettingsType (logrotation.xsd). The graphical representation of the type is as follows:

The log-rotation node is required. specifies log limits. On achieving a limit the log file is removed and new log file is started. Data type: LogRotationConditionType (logrotation.xsd) The log-bysize node is required. It specifies maximum size of a log file in bytes. Data type: integer.

642

Supported Operations

The log-bytime node is required. It specifies interval of logging. Data type: string. Allowed values: Daily | Weekly | Monthly

The log-max-num-files node is optional. It specifies how many processed by statistical utilities log files are stored on the server. Data type: integer. The log-compress node is optional. It specifies if log files are compressed. Data type: boolean. The log-email node is optional. It specifies e-mail address on which processed log files will be sent. Data type: string.

Note: In API RPC 1.5.0.0 and earlier versions, the type of this node is emailType (common.xsd).

Filtering Issues
Filtering is the way the request XML packet indicates the object (a web user or several) to which the operation will be applied. The request XML packet filters web user accounts using a special <filter> node. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

In this section:
Log Rotation Filter ............................................................................................. 643 filter-id ............................................................................................................... 643

Supported Operations

643

Log Rotation Filter


The filter for this operator is presented by type logRotationFilterType (logrotation.xsd) and structured as follows:

The domain-id node is required. It specifies ID of a domain. Data type: integer. The client-id node is required. It specifies ID of a client. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string (UTF-8). The client-login node is required. It specifies the client login name. Data type: string.

Remarks The filter node can be left blank (<filter/>). In this case all domains available for user specified by login credentials will be matched. A single filter can specify multiple domains defined either by ID, name, client ID or client name in the second. For example, the filter that matches all domains of the clients with IDs 8,9, and 10 looks as follows:
<filter> <client-id>8</client-id> <client-id>9</client-id> <client-id>10</client-id> </filter>

644

Supported Operations

filter-id

If an operation in a request packet uses filters, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet. Domain ID Domain name Client ID Client login name

It is done to trace request parameters in case of error. Data type: anySimple.

Changing Log Rotation Settings


The set operation is used to change settings of Log Rotation.

In this section:
Request Packet Structure.................................................................................. 644 Request Samples .............................................................................................. 645 Response Packet Structure ............................................................................... 647 Response Samples ........................................................................................... 648

Request Packet Structure


A request XML packet changing Log Rotation settings includes the set operation node:
<packet version="1.5.0.0"> <log-rotation> <set> </set> </log-rotation> </packet>

The set node is presented by type LogRotationSetInput (logrotation.xsd), and its graphical representation is as follows:

Supported Operations

645

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 642) section. Data type: logRotationFilterType (logrotation.xsd). The settings node is required. It specifies Log Rotation settings. For details, refer to the Log Rotation Settings (on page 641) section. Data type: LogRotationSettingsType (logrotation.xsd).

Remarks You can use different filtering rules in a single packet. Add as many set operations as the number of different filtering rules.
<packet version="1.5.0.0"> <log-rotation> <set> </set> ... <set> </set> </log-rotation> </packet>

Request Samples
Changing settings of a single domain The following request packet changes Log Rotation settings of domain example.com:
<packet version="1.5.0.0"> <log-rotation> <set> <filter> <domain-name>example.com</domain-name> </filter> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </set> </log-rotation> </packet>

646

Supported Operations

Changing settings of multiple domains The following request packet changes Log Rotation settings of domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <set> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> </settings> </set> </log-rotation> </packet>

The following request packet changes Log Rotation settings of domain example.com and the domain with ID 6:
<packet version="1.5.0.0"> <log-rotation> <set> <filter> <domain-id>6</domain-id> </filter> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </set> <set> <filter> <domain-name>example.com</domain-name> </filter> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </set> </log-rotation> </packet>

Supported Operations

647

The following request packet changes Log Rotation settings of all domains available for a packet sender:
<packet version="1.5.0.0"> <log-rotation> <set> <filter/> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> </settings> </set> </log-rotation> </packet>

Response Packet Structure


The set node of the output XML packet is presented by type LogRotationSetOutput (logrotation.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the set operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the set operation fails. Data type: string. The filter-id node is required. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple.

648

Supported Operations

The id node is optional. If the set operation succeeds, it holds the ID of the domain matched by the filtering rule. Data type: integer.

Response Samples
Changing settings of a single domain The following request packet changes Log Rotation settings of domain example.com:
<packet version="1.5.0.0"> <log-rotation> <set> <filter> <domain-name>example.com</domain-name> </filter> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </set> </log-rotation> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <log-rotation> <set> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>33</id> </result> </set> </log-rotation> </packet>

If the domain was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>example.com</filter-id> </result> </set> </log-rotation> </packet>

Supported Operations

649

If a packet sender has no rights to manage physical hosting, the response looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get> <result> <status>error</status> <errcode>1006</errcode> <errtext>Access denied</errtext> <filter-id>example.com</filter-id> </result> </get> </log-rotation> </packet>

If the domain is not hosted physically, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get> <result> <status>error</status> <errcode>1034</errcode> <errtext>The domain is not hosted physically</errtext> <filter-id>example.com</filter-id> </result> </get> </log-rotation> </packet>

Changing settings of multiple domains The following request packet changes Log Rotation settings of domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <set> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> </settings> </set> </log-rotation> </packet>

650

Supported Operations

If the client with ID 5 was not found on the server and the client with ID 8 runs two domains (ID 17 and 29) the response from the server looks as follows:
<packet version="1.5.0.0"> <set> <log-rotation> <result> <status>error</status> <errcode>1015</errcode> <errtext>client does not exist</errtext> <filter-id>5</filter-id> </result> </set> <set> <result> <status>ok</status> <filter-id>8</filter-id> <id>17</id> </result> </set> <set> <result> <status>ok</status> <filter-id>8</filter-id> <id>29</id> </result> </set> </log-rotation> </packet>

Retrieving Log Rotation Settings


The get operation is used to change settings of Log Rotation.

In this section:
Request Packet Structure.................................................................................. 651 Request Samples .............................................................................................. 652 Response Packet Structure ............................................................................... 653 Response Samples ........................................................................................... 654

Supported Operations

651

Request Packet Structure


A request XML packet retrieving Log Rotation settings includes the get operation node:
<packet version="1.5.0.0"> <log-rotation> <get> </get> </log-rotation> </packet>

The get node is presented by type LogRotationGetInput (logrotation.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 642) section. Data type: logRotationFilterType (logrotation.xsd).

Remarks You can use different filtering rules in a single packet. Add as many get operations as the number of different filtering rules.
<packet version="1.5.0.0"> <log-rotation> <get> </get> ... <get> </get> </log-rotation> </packet>

652

Supported Operations

Request Samples
Retrieving settings of a single domain The following request packet retrieves Log Rotation settings of domain example.com:
<packet version="1.5.0.0"> <log-rotation> <get> <filter> <domain-name>example.com</domain-name> </filter> </get> </log-rotation> </packet>

Retrieving settings of multiple domains The following request packet retrieves Log Rotation settings of domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <get> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </get> </log-rotation> </packet>

The following request packet retrieves Log Rotation settings of domain example.com and the domain with ID 6:
<packet version="1.5.0.0"> <log-rotation> <get> <filter> <domain-id>6</domain-id> </filter> </get> <get> <filter> <domain-name>example.com</domain-name> </filter> </get> </log-rotation> </packet>

The following request packet retrieves Log Rotation settings of all domains available for packet sender:
<packet version="1.5.0.0"> <log-rotation> <get> <filter/> </get> </log-rotation> </packet>

Supported Operations

653

Response Packet Structure


The get node of the output XML packet is presented by type LogRotationGetOutput (logrotation.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the get operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. The filter-id node is required. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type:anySimple. The id node is optional. If the get operation succeeds, it holds the ID of the domain matched by the filtering rule. Data type: integer. The settings node is optional. It specifies Log Rotation settings. For details, refer to the Log Rotation Settings (on page 641) section. Data type: LogRotationSettingsType (logrotation.xsd).

654

Supported Operations

Response Samples
Retrieving settings of a single domain The following request packet retrieves Log Rotation settings of domain example.com:
<packet version="1.5.0.0"> <log-rotation> <get> <filter> <domain-name>example.com</domain-name> </filter> </get> </log-rotation> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <log-rotation> <get> <result> <filter-id>example.com</filter-id> <id>33</id> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </result> </get> </log-rotation> </packet>

If the domain was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>example.com</filter-id> </result> </get> </log-rotation> </packet>

Supported Operations

655

If a packet sender has no rights to manage physical hosting, the response looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get> <result> <status>error</status> <errcode>1006</errcode> <errtext>Access denied</errtext> <filter-id>example.com</filter-id> </result> </get> </log-rotation> </packet>

If the domain is not hosted physically, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get> <result> <status>error</status> <errcode>1034</errcode> <errtext>The domain is not hosted physically</errtext> <filter-id>example.com</filter-id> </result> </get> </log-rotation> </packet>

Retrieving settings of multiple domains The following request packet retrieves Log Rotation settings of domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <get> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </get> </log-rotation> </packet>

If the client with ID 5 was not found on the server and the client with ID 8 runs two domains (ID 17 and 29) the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get> <result> <status>error</status> <errcode>1015</errcode> <errtext>client does not exist</errtext> <filter-id>5</filter-id> </result> </get> <get> <result>

656

Supported Operations <status>ok</status> <filter-id>8</filter-id> <id>17</id> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </result> </get> <get> <result> <status>ok</status> <filter-id>8</filter-id> <id>29</id> <settings> <log-condition> <log-bysize>2073741824</log-bysize> </log-condition> <log-max-num-files>1</log-max-num-files> <log-compress>true</log-compress> </settings> </result> </get> </log-rotation> </packet>

Enabling Log Rotation Service


Use the enable operation to enable Log Rotation service on domains.

In this section:
Request Packet Structure.................................................................................. 656 Request Samples .............................................................................................. 657 Response Packet Structure ............................................................................... 659 Response Samples ........................................................................................... 660

Request Packet Structure


A request XML packet enabling Log Rotation service includes the enable operation node:
<packet version="1.5.0.0"> <log-rotation> <enable> </enable> </log-rotation> </packet>

Supported Operations

657

The enable node is presented by type LogRotationEnableInput (logrotation.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 642) section. Data type: logRotationFilterType (logrotation.xsd).

Remarks You can use different filtering rules in a single packet. Add as many enable operations as the number of different filtering rules.
<packet version="1.5.0.0"> <log-rotation> <enable> </enable> ... <enable> </enable> </log-rotation> </packet>

Request Samples
Enabling Log Rotation service on a single domain The following request packet enables Log Rotation service on domain example.com:
<packet version="1.5.0.0"> <log-rotation> <enable> <filter> <domain-name>example.com</domain-name> </filter> </enable> </log-rotation> </packet>

658

Supported Operations

Enabling Log Rotation service on multiple domain The following request packet enables Log Rotation service on domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <enable> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </enable> </log-rotation> </packet>

The following request packet enables Log Rotation service on domain example.com and the domain with ID 6:
<packet version="1.5.0.0"> <log-rotation> <enable> <filter> <domain-id>6</domain-id> </filter> </enable> <enable> <filter> <domain-name>example.com</domain-name> </filter> </enable> </log-rotation> </packet>

The following request packet enables Log Rotation service on all domains available for packet sender:
<packet version="1.5.0.0"> <log-rotation> <enable> <filter/> </enable> </log-rotation> </packet>

Supported Operations

659

Response Packet Structure


The enable node of the output XML packet is presented by type LogRotationEnableOutput (logrotation.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the enable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the enable operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the enable operation fails. Data type: string. The filter-id node is required. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type:anySimple. The id node is optional. If the enable operation succeeds, it holds the ID of the domain matched by the filtering rule. Data type: integer.

660

Supported Operations

Response Samples
Enabling Log Rotation service on a single domain The following request packet enables Log Rotation service on domain example.com:
<packet version="1.5.0.0"> <log-rotation> <enable> <filter> <domain-name>example.com</domain-name> </filter> </enable> </log-rotation> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <log-rotation> <enable> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>33</id> </result> </enable> </log-rotation> </packet>

If the domain was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <enable> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>example.com</filter-id> </result> </enable> </log-rotation> </packet>

Enabling Log Rotation service on multiple domains The following request packet enables Log Rotation service on domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <enable> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </enable> </log-rotation></packet>

Supported Operations

661

If the client with ID 5 was not found on the server and the client with ID 8 runs two domains (ID 17 and 29) the response from the server looks as follows:

<packet version="1.5.0.0"> <enable> <log-rotation> <result> <status>error</status> <errcode>1015</errcode> <errtext>client does not exist</errtext> <filter-id>5</filter-id> </result> </enable> <enable> <result> <status>ok</status> <filter-id>8</filter-id> <id>17</id> </result> </enable> <enable> <result> <status>ok</status> <filter-id>8</filter-id> <id>29</id> </result> </enable> </log-rotation> </packet>

662

Supported Operations

Disabling Log Rotation Service


Use the disable operation to disable Log Rotation service on domains.

In this section:
Request Packet Structure.................................................................................. 663 Request Samples .............................................................................................. 664 Response Packet Structure ............................................................................... 665 Response Samples ........................................................................................... 666

Supported Operations

663

Request Packet Structure


A request XML packet disabling Log Rotation service includes the disable operation node:
<packet version="1.5.0.0"> <log-rotation> <disable> </disable> </log-rotation> </packet>

The disable node is presented by type LogRotationDisableInput (logrotation.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 642) section. Data type: logRotationFilterType (logrotation.xsd).

Remarks You can use different filtering rules in a single packet. Add as many disable operations as the number of different filtering rules.
<packet version="1.5.0.0"> <log-rotation> <disable> </disable> ... <disable> </disable> </log-rotation> </packet>

664

Supported Operations

Request Samples
Disabling Log Rotation service on a single domain The following request packet disables Log Rotation service on domain example.com:
<packet version="1.5.0.0"> <log-rotation> <disable> <filter> <domain-name>example.com</domain-name> </filter> </disable> </log-rotation> </packet>

Disabling Log Rotation service on multiple domain The following request packet disables Log Rotation service on domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <disable> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </disable> </log-rotation> </packet>

The following request packet disables Log Rotation service on domain example.com and the domain with ID 6:
<packet version="1.5.0.0"> <log-rotation> <disable> <filter> <domain-id>6</domain-id> </filter> </disable> <disable> <filter> <domain-name>example.com</domain-name> </filter> </disable> </log-rotation> </packet>

The following request packet disables Log Rotation service on all domains available for packet sender:
<packet version="1.5.0.0"> <log-rotation> <disable> <filter/> </disable> </log-rotation> </packet>

Supported Operations

665

Response Packet Structure


The disable node of the output XML packet is presented by type LogRotationDisableOutput (logrotation.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the disable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the disable operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the disable operation fails. Data type: string. The filter-id node is required. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple. The id node is optional. If the disable operation succeeds, it holds the ID of the domain matched by the filtering rule. Data type: integer.

666

Supported Operations

Response Samples
Disabling Log Rotation service on a single domain The following request packet disables Log Rotation service on domain example.com:
<packet version="1.5.0.0"> <log-rotation> <disable> <filter> <domain-name>example.com</domain-name> </filter> </disable> </log-rotation> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <log-rotation> <disable> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>33</id> </result> </disable> </log-rotation> </packet>

If the domain was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <disable> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>example.com</filter-id> </result> </disable> </log-rotation> </packet>

Disabling Log Rotation service on multiple domains The following request packet disables Log Rotation service on domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <disable> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </disable> </log-rotation> </packet>

Supported Operations

667

If the client with ID 5 was not found on the server and the client with ID 8 runs two domains (ID 17 and 29) the response from the server looks as follows:
<packet version="1.5.0.0"> <disable> <log-rotation> <result> <status>error</status> <errcode>1015</errcode> <errtext>client does not exist</errtext> <filter-id>5</filter-id> </result> </disable> <disable> <result> <status>ok</status> <filter-id>8</filter-id> <id>17</id> </result> </disable> <disable> <result> <status>ok</status> <filter-id>8</filter-id> <id>29</id> </result> </disable> </log-rotation> </packet>

Checking Status of Log Rotation Service


Use the get-status operation to retrieve status of Log Rotation service on domains.

In this section:
Request Packet Structure.................................................................................. 668 Request Samples .............................................................................................. 669 Response Packet Structure ............................................................................... 670 Response Samples ........................................................................................... 671

668

Supported Operations

Request Packet Structure


A request XML packet retrieving status of Log Rotation service includes the get-status operation node:
<packet version="1.5.0.0"> <log-rotation> <get-status> </get-status> </log-rotation> </packet>

The get-status node is presented by type LogRotationDisableInput (logrotation.xsd), and its graphical representation is as follows:

The filter node is required. Specifies the filtering rule. For more information, refer to the Filtering Issues (on page 642) section. Data type: logRotationFilterType (logrotation.xsd).

Remarks You can use different filtering rules in a single packet. Add as many get-status operations as the number of different filtering rules.
<packet version="1.5.0.0"> <log-rotation> <get-status> </get-status> ... <get-status> </get-status> </log-rotation> </packet>

Supported Operations

669

Request Samples
Retrieving status of Log Rotation service on a single domain The following request packet retrieves status of Log Rotation service on domain example.com:
<packet version="1.5.0.0"> <log-rotation> <get-status> <filter> <domain-name>example.com</domain-name> </filter> </get-status> </log-rotation> </packet>

Retrieving status of Log Rotation service on multiple domain The following request packet retrieves status of Log Rotation service on domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <get-status> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </get-status> </log-rotation> </packet>

The following request packet retrieves status of Log Rotation service on domain example.com and the domain with ID 6:
<packet version="1.5.0.0"> <log-rotation> <get-status> <filter> <domain-id>6</domain-id> </filter> </get-status> <get-status> <filter> <domain-name>example.com</domain-name> </filter> </get-status> </log-rotation> </packet>

The following request packet retrieves status of Log Rotation service on all domains available for packet sender:
<packet version="1.5.0.0"> <log-rotation> <get-status> <filter/> </get-status> </log-rotation> </packet>

670

Supported Operations

Response Packet Structure


The get-status node of the output XML packet is presented by type LogRotationGetStatusOutput (logrotation.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-status operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the get-status operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get-status operation fails. Data type: string. The filter-id node is required. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (on page 643) section. Data type: anySimple. The id node is optional. If the get-status operation succeeds it holds the ID of the domain matched by the filtering rule. Data type: integer. The enabled node is optional. If the get-status operation succeeds, it holds status of the service on the domain. Data type: integer.

Supported Operations

671

Response Samples
Retrieving status of Log Rotation service on a single domain The following request packet retrieves status of Log Rotation service on domain example.com:
<packet version="1.5.0.0"> <log-rotation> <get-status> <filter> <domain-name>example.com</domain-name> </filter> </get-status> </log-rotation> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <log-rotation> <get-status> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>33</id> </result> </get-status> </log-rotation> </packet>

If the domain was not found, the response from the server looks as follows:
<packet version="1.5.0.0"> <log-rotation> <get-status> <result> <status>error</status> <errcode>1013</errcode> <errtext>domain does not exist</errtext> <filter-id>example.com</filter-id> </result> </get-status> </log-rotation> </packet>

672

Supported Operations

Retrieving status of Log Rotation service on multiple domains The following request packet retrieves status of Log Rotation service on domains used by the clients with ID 5 and ID 8:
<packet version="1.5.0.0"> <log-rotation> <get-status> <filter> <client-id>5</client-id> <client-id>8</client-id> </filter> </get-status> </log-rotation> </packet>

If the client with ID 5 was not found on the server and the client with ID 8 runs two domains (ID 17 and 29) the response from the server looks as follows:
<packet version="1.5.0.0"> <get-status> <log-rotation> <result> <status>error</status> <errcode>1015</errcode> <errtext>client does not exist</errtext> <filter-id>5</filter-id> </result> </get-status> <get-status> <result> <status>ok</status> <filter-id>8</filter-id> <id>17</id> </result> </get-status> <get-status> <result> <status>ok</status> <filter-id>8</filter-id> <id>29</id> </result> </get-status> </log-rotation> </packet>

Supported Operations

673

Managing Mail on Domain Level


Operator: <mail> XML Schema: mail_input.xsd, mail_output.xsd, plesk_mailname.xsd Plesk version: Plesk 7.5.4 for UNIX and later | Plesk 8.1 for Windows and later API RPC version: 1.3.5.0 and higher Plesk user: Plesk Administrator, Plesk client Description The mail operator allows performing operations on mail service and mail accounts on a particular domain. The mail service settings specify whether the Webmail application is turned on for a particular domain. These settings also specify the mail service behaviour when an incoming message is addressed to a non-existent user. Mail user is the less privileged Plesk user. Creating Plesk mail user is equivalent to creating a special mail account on the specified domain. This operation is allowed to Plesk Administrator and Plesk client. Mail account presents a collection of settings and lists of various objects. A mail account is created on a certain domain and remains associated with this domain during its lifetime. All objects created within the mail account (autoresponders, redirects, files, etc.) share the disk space of the domain that owns this mail account. Mail accounts are uniquely identified by name/ID of the parent domain and by mail user name. Mail user settings specify the following: Mail name and password, mail aliases Mail user access to his mail account through Plesk GUI Mail box settings Mail user permissions Antivirus protection Mail group members (if a mail account is used as a mail group) Groups in which a mail account has membership Files to store in the repository Automatic response messages Mail addresses to which all incoming correspondence will be redirected automatically

For more details, refer to the Mail Service Settings (see page 675) and Mail User Account Settings (see page 677) sections.

674

Supported Operations

Supported operations

CREATE (see page 691) creates a mail account on a specified domain and sets a collection of settings for it UPDATE (see page 695) serves to update mail account settings. It is specially designed to operate lists of mail group members, repository files, and automatic reply messages set for the mail account GET_INFO (see page 703) serves to retrieve various information about the specified mail accounts from Plesk database REMOVE (see page 708) removes the specified mail account and all its settings from Plesk database ENABLE (see page 712) turns on the mail service on the specified domain DISABLE (see page 712) turns off the mail service on the specified domain SET_PREFS (see page 717) sets mail service preferences for the specified domains GET_PREFS (see page 721) gets mail service preferences set for the specified domains RENAME (see page 725) renames the specified mail box

Supported Operations

675

In this section:
Mail Service Preferences................................................................................... 675 Mail Account Settings ........................................................................................ 677 Filtering Issues .................................................................................................. 690 Creating Mail Accounts ..................................................................................... 691 Modifying Mail Account Settings ........................................................................ 695 Getting Mail Account Settings ........................................................................... 703 Deleting Mail Accounts ...................................................................................... 708 Enabling/Disabling Mail Service on Domain ...................................................... 712 Setting Mail Service Preferences....................................................................... 717 Getting Mail Service Preferences ...................................................................... 721 Renaming Mail Accounts ................................................................................... 725

Mail Service Preferences


Mail service settings are defined in the MailPreferences complex type (plesk_mailname.xsd). This type is structured as follows:

The nonexistent-user node is optional. It specifies the way the server handles messages sent to unknown mail users (not registered on the domain). By default, such messages are sent back to the sender with a message: this address no longer accepts mail. The bounce node is used to modify the default rejection message. Data type: string. The forward node specifies the mail address to which undelivered mail should be forwarded. Data type: string. The reject node is used to reject such mail messages (they will not be accepted by the mail server). Data type: none. The webmail node is optional. It specifies whether mail users will have access to their mail via a WebMail application. Data type: Boolean. The spam-protect-sign node is optional. If the DomainKeys spam protection is available on the server, the node specifies whether the spam protection is turned on on the domain. Data type: Boolean. (Available since API RPC version 1.5.2.1.)

676

Supported Operations

For API RPC version 1.5.2.1, the following packet sets mail service preferences for three domains:
<packet version=1.5.2.1> <mail> <set_prefs> <filter> <domain_id>12</domain_id> <domain_id>14</domain_id> <domain_id>15</domain_id> </filter> <prefs> <nonexistent-user> <reject/> </nonexistent-user> <webmail>true</webmail> <spam-protect-sign>true</spam-protect-sign> </prefs> </set_prefs> </mail> </packet>

For API RPC version 1.5.2.0 and earlier, a packet which sets mail service preferences for three domains can look as follows:
<packet version=1.4.2.0> <mail> <set_prefs> <filter> <domain_id>12</domain_id> <domain_id>14</domain_id> <domain_id>15</domain_id> </filter> <prefs> <nonexistent-user> <reject/> </nonexistent-user> <webmail>true</webmail> </prefs> </set_prefs> </mail> </packet>

Supported Operations

677

Mail Account Settings


Mail account settings are specified by complex type mailnameType (plesk_mailname.xsd). It is structured as follows:

The id node is optional. It specifies the identifier of the mail user (if this user already exists in Plesk database). Data type: integer.

678

Supported Operations

The name node is required. It specifies the name of the mail user. Data type: string. The cp_access node is optional. It specifies a collection of Plesk GUI settings for the mail user. Data type: none. See the structure of this node in the Control Panel Settings (see page 680) section. The mailbox node is optional. It specifies a collection of mail box settings. Data type: none. See the structure of this node in the Mail Box Settings (see page 681) section. The mailbox-usage node is optional. It specifies the amount of disk space used by a mail box. Data type: long.

Note: This node is supported in API RPC 1.5.2.0 and later versions. The redirect node is optional. It enables the redirect feature for the mail account and specifies the email address where the correspondence will be redirected. Data type: none. See the structure of this node in the Redirect Settings (see page 682) section. The mailgroup node is optional. It defines the list of mail addresses for which the mail account will serve as a mail group. This feature implements redirecting mail to multiple addresses. Data type: none. See the structure of this node in the Mail Group Settings (see page 684) section. The group node is optional. It specifies a mail group in which the given mail account has a membership. Data type: string. The alias node is optional. It specifies an alternative name for the given mail name (e.g., the bob alias set for bfisher@example.com means that all mail sent to bob@example.com and to the original address will get to the same mail box). Data type: string. The autoresponders node is optional. It defines a collection of automatic response messages and their settings that will be sent from the given mail account. Data type: none. See the structure of this node in the Automatic response settings (see page 685) section. The repository node is optional. It contains a list of files stored in the repository of the given mail account. These files can be attached to automatic response messages if necessary. Data type: none. See the structure of this node in the Repository Settings (see page 687) section. The password node is optional. It specifies the password used by mail user to access the mail box. Data type: string. The password_type node is optional. It specifies the type of the password. Data type: string. Allowed values: plain | crypt. The antivir node is optional. It specifies the antivirus protection settings for the incoming/outgoing correspondence. Data type: string. Allowed values: off | inout | in | out. This node is renamed to antivir in API RPC 1.4.2.0. In the earlier versions of API RPC, it is called drweb. The permissions node is optional. It specifies a collection of mail user permissions. Data type: MailUserPermission (plesk_mailname.xsd). This node is supported in API RPC 1.4.2.0 and later. See the structure of this node in the Mail User Permissions (see page 688) section.

Supported Operations

679

The following sample packet creates a mail account and sets a collection of settings for it:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>bfischer</name> <cp_access> <enabled>true</enabled> </cp_access> <mailbox> <enabled>true</enabled> <quota>10485760</quota> </mailbox> <alias>bob</alias> <antivir>true</antivir> <permissions> <cp_access>true</cp_access> <manage_drweb>true</manage_drweb> <manage_spamfilter>true</manage_spamfilter> </permissions> </mailname> </filter> </create> </mail> </packet>

In this section:
Control Panel Settings....................................................................................... 680 Mail Box Settings .............................................................................................. 681 Redirecting Settings .......................................................................................... 682 Mail Group Settings ........................................................................................... 684 Automatic Response Settings ........................................................................... 685 Repository Settings ........................................................................................... 687 Mail User Permissions ....................................................................................... 688

680

Supported Operations

Control Panel Settings


The cp_access node is used to enable/disable access to the personal mail account through control panel (CP). If CP access is allowed, the cp_access node can specify a collection of GUI preferences for the mail user. The cp_access node does not have a special data type, it is nested within the mailname node (see the structure of this node in the Mail User Account Settings (see page 677) section). It is structured as follows:

The enabled node is optional. It is used to enable the CP access to the mail user page. Data type: boolean. The access node is required. It specifies a collection of CP access settings. Data type: none. The locale node is optional. It specifies what language is used when displaying the CP to the mail user. Data type: string. Default value: en-US.

Note: In API RPC v.1.5.0.0 and later, use four-letter locale names (RFC 1766). In API RPC v.1.4.2.0 and earlier versions, you can also use two-letter locale names. If you specify two-letter locale name in a request packet, and request packet protocol is API RPC v.1.5.0.0 or later, you will receive the error (error code 1019). If you use API RPC v.1.4.2.0 or earlier versions, the operations will be successfully processed. If you use get_info to retrieve the value of this parameter, the four-letter locale name is returned. The skin_id node is optional. It specifies what interface skin (by ID) is used when displaying the CP to the mail user. Data type: integer. The multiply_login node is optional. It allows/prohibits creating multiple simultaneous CP sessions with the mail user credentials. Data type: boolean. The disable_lock_screen node is optional. If set to true, it prevents mail user from working with CP until the GUI is completely loaded. Data type: boolean.

Supported Operations

681

The following sample packet creates mail account and sets up CP access to the mail user page:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>bfischer</name> <cp_access> <enabled>true</enabled> <access> <locale>EN-US</locale> <skin_id>11</skin_id> <multiply_login>true</multiply_login> </access> </cp_access> </mailname> </filter> </create> </mail> </packet>

Mail Box Settings


The mailbox node is used to enable/disable the use of a mail box created for a particular mail account, and to restrict the size of the mail box as well. The mailbox node does not have a special data type, it is nested within the mailname (see page 677) node. It is structured as follows:

The enabled node is optional. It shows whether the mail user can use the mail box created on Plesk server. Data type: Boolean. Default value: true. The quota node is optional. It specifies the maximum size of the mail box (in bytes). Data type: integer.

682

Supported Operations

The following sample packet creates a mail account, enables the use of mail box on it, and specifies the limit for the mail box size:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>bfischer</name> <mailbox> <enabled>true</enabled> <quota>1024000</quota> </mailbox> </mailname> </filter> </create> </mail> </packet>

Redirecting Settings
Mail account can redirect all incoming correspondence to a specified e-mail address. To enable the redirect feature for a particular mail account, request packet should contain the redirect node within the mailname parent node. The redirect node does not have a special data type, it is defined within the parent node as follows:

The enabled node is required. It enables the redirect feature for a particular mail account. Data type: boolean. Default value: false. The address node is optional. It holds an email address to which the correspondence will be redirected. Data type: string.

Supported Operations

683

The following sample packet creates a mail account, and makes it redirect all incoming messages to techdept@example.com:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>bfischer</name> <redirect> <enabled>true</enabled> <address>techdept@example.com</address> </redirect> </mailname> </filter> </create> </mail> </packet>

684

Supported Operations

Mail Group Settings


Mail account can serve as a mail group: It can be associated with a list of mail addresses to which it will send all incoming correspondence. To enable the mail group functionality for a particular mail account, request packet should contain the mailgroup node within the mailname parent node. The mailgroup node does not have a special data type, it is defined within the parent node as follows:

The enabled node is required. It enables the mail group functionality for the mail account. Data type: boolean. Default value: false. The address node is optional. It holds an email address of this mail group member. Data type: string.

The following sample packet creates a mail account and makes it act as a mail group for the list of email addresses:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>bfischer</name> <mailgroup> <enabled>true</enabled> <address>techdept@example.com</address> <address>automation@example.com</address> </mailgroup> </mailname> </filter> </create> </mail> </packet>

Supported Operations

685

Automatic Response Settings


The automatic response settings are specified for each mail account by the list of autoresponder objects. An autoresponder object is a collection of conditions (events) on which the automatic response message is sent back. In addition, this object specifies the text of this response and the attachment (a file stored in the a mail box repository). Finally, it can specify how this automatic response will act. The list of autoresponders is specified in the autoresponders node nested within the mailname parent node and structured as follows:

The enabled node is optional. It enables/disables the feature on the mail account. Data type: boolean. Default value: false. The autoresponder node is optional. It specifies an autoresponder object. Data type: none. See the structure of this node below.

The autoresponder node does not have a special data type. It is structured within the autoresponders node as follows:

The name node is required. It specifies the name of the autoresponder. Data type: string.

686

Supported Operations

The enabled node is optional. It enables/disables the use of the autoresponder object. Data type: boolean. Default value: false. The keystr node is optional. It specifies the key string in the incoming message that will enable this autoresponder sending back its message. Data type: string. The key_where node is optional. It specifies the part of an incoming message (body, subject) where the key string should be searched. Data type: string. Allowed values: subj | no | body. The subject node is optional. It specifies the subject field in the incoming message header that will enable this autoresponder sending its message back. Data type: string. The reply_to node is optional. It specifies the Reply to field in an incoming message header that will enable the autoresponder sending back its message. Data type: string. The content_type node is optional. It specifies the Content type field in the incoming message header that will enable the autoresponder sending back its message. Data type: string. Allowed values: text/html | text/plain. The charset node is optional. It specifies the charset field in the incoming message header that will enable the autoresponder sending back its message. Data type: string. The text node is optional. It specifies the text of the automatic response message. Data type: string. The ans_freq node is optional. It specifies the maximum number of automatic replies that can be sent back to the mail address. Data type: integer. The mem_limit node is optional. It specifies the maximum number of unique email addresses that can be stored. Data type: integer. The attachment node is optional. It specifies the name of the file to be attached to the response message. Data type: string. The forward node is optional. It specifies the email address to which the original message will be forwarded. Data type: string.

Supported Operations

687

The following sample packet creates a mail account and specifies autorespoder settings for it:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>123</domain_id> <mailname> <name>bfischer</name> <autoresponders> <enabled>true</enabled> <autoresponder> <name>motorola</name> <subject>Regarding controllers</subject> <text>Your answer will be processed in the nearest 10 days. Thank you.</text> <forward>techdept@technolux.co.uk</forward> </autoresponder> </autoresponders> </mailname> </filter> </create> </mail> </packet>

Repository Settings
Every mail account is provided with a personal file repository. The stored files can be used as attachments to automatically sent messages, or for other needs. A repository presents a collection of file objects, each describing a single file as file name and file contents. The repository node does not have a special data type. It is defined within the parent type mailnameType.

The file node is required. It specifies a single file object. Data type: none. The name node is required. It specifies the file name. Data type: string. The content node is optional. It keeps the file contents. This node can be missing in the response packet if the request one asks for a list of file names only. Data type: base64.

688

Supported Operations

The following get_info response packet returns the list of files stored in the repository of the specified mail account:
<packet version=1.4.2.0> <mail> <get_info> <result> <status>ok</status> <mailname> <name>techdept</name> <repository> <file> <name>attach1.txt</name> </file> <file> <name>attach2.txt</name> </file> </repository> </mailname> </result> </get_info> </mail> </packet>

Mail User Permissions


Starting from API RPC 1.5.0.0. there are two possible ways of retrieving mail user permissions. The way used in the API RPC v.1.4.2.0 and earlier versions is parameterdependable. The other way is parameter-undependable.

In this section:
API RPC v.1.5.0.0 and Later Versions............................................................... 688 API RPC v.1.4.2.0 and Earlier Versions ............................................................ 689

API RPC v.1.5.0.0 and Later Versions


In the API RPC v.1.5.0.0 and later versions you should manage mail user permissions according to the following XML schema:

The permission node is required. It specifies mail user permissions. Data type: PleskPermissionType (plesk_common.xsd).

Supported Operations

689

The name node is required. It specifies a permission name. Data type: sting. The value node is required. It specifies a permission value. Data type: anySimple.

Sample The following packet creates a mail account and sets permissions for it:
<packet version=1.5.0.0> <mail> <create> <filter> <domain_id>123</domain_id> <mailname> <name>bfischer</name> <permissions> <permission> <name>cp_access</name> <value>true</value> </permission> <permission> <name>manage_drweb</name> <value>true</value> </permission> <permission> <name>manage_spamfilter</name> <value>true</value> </permission> </permissions> </mailname> </filter> </create> </mail> </packet>

API RPC v.1.4.2.0 and Earlier Versions


Mail user permissions are defined by complex data type MailUserPermission (plesk_mailname.xsd). This type is structured as follows:

690

Supported Operations

The cp_access node is optional. It allows/prohibits the mail user access to their mail box through Plesk GUI. Data type: Boolean. The manage_drweb node is optional. It allows/prohibits the mail user changing settings of the antivirus software integrated with Plesk (DrWeb). Data type: boolean. The manage_spamfilter node is optional. It allows/prohibits the mail user changing settings of the spam filtering software integrated with Plesk (SpamAssassin). Data type: boolean.

The following packet creates a mail account and sets permissions for it:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>123</domain_id> <mailname> <name>bfischer</name> <permissions> <cp_access>true</cp_access> <manage_drweb>true</manage_drweb> <manage_spamfilter>true</manage_spamfilter> </permissions> </mailname> </filter> </create> </mail> </packet>

Filtering Issues
,Filtering is the way request packets pick out mail accounts to which the requested operation will be applied. The mail operator uses filtering in most of its operations. The filter node used in operations create and update is presented by the mailnameFilterType complex type (mail_input.xsd). This data type is structured as follows:

The domain_id node is required. It specifies the domain ID. Data type: integer. The mailname node is required. It holds a collection of mail account settings that will be affected. Data type: mailnameType (plesk_mailname.xsd).

This filter can pick out one to many mail account existing on the same domain.

Supported Operations

691

When filtering mail accounts, we never specify the entire mail name. The domain part of it is specified by the domain_id node, and the mail user name is specified by the name node within the mailname section.
<packet version=1.4.2.0> <mail> <update> <add> <filter> <domain_id>12</domain_id> <mailname> <name>ann</name> <mailgroup> <enabled>true</enabled> <address>techdept@example.com</address> <address>findept@example.com</address> <address>techgroup@example.com</address> </mailgroup> </mailname> </filter> </add> </update> </mail> </packet>

The packet above modifies settings of the ann@example.com mail account (a mail group) with several new mail addresses. The mail operator uses two more types of filtering (type GetInfoAdvancedFilter, type mailFilterType). These types are designed for particular cases and considered in the relevant sections (Getting Mail Account Settings (see page 703) and Deleting Mail Accounts (see page 708), respectively).

Creating Mail Accounts


Mail user account can be created on the specified domain either by Plesk Administrator or by Plesk client. To register new mail account in Plesk database, it is enough to specify some general setup information, namely: the domain ID where the mail account will be registered, and the mail account name. In addition, you can specify various mail account settings (all of them are optional): Mail user access to the account through Plesk GUI Mail box size Mail box alias Mail user permissions Antivirus protection Mail group members (if the account acts as a mail group) Mail groups in which the mail account has membership Files to store in the repository Automatic response messages Mail addresses to which all incoming correspondence will be redirected automatically

692

Supported Operations

A mail account can have all these settings specified, or it can hold just some of them. You can specify these settings when creating a mail account or later (they can be set using the set_prefs operation).

In this section:
Request Packet Structure.................................................................................. 692 Request Samples .............................................................................................. 692 Response Packet Structure ............................................................................... 694 Response Samples ........................................................................................... 695

Request Packet Structure


A request XML packet creating a mail account in Plesk database includes the create operation node:
<packet version=1.4.2.0> <mail> <create> </create> </mail> </packet>

The create node does not have a separate type, it is nested within the MailTypeRequest type (mail_input.xsd). The create node has the following graphics representation:

The filter node is required. It holds a collection of data describing mail accounts to be created. Data type: mailnameFilterType (plesk_mailname.xsd) The domain_id node is required. It uniquely identifies the domain on which the mail account will be created. Data type: integer. The mailname node is required. It defines the name of a mail account, and a collection of mail account settings (if any specified). Data type: mailnameType (plesk_mailname.xsd). See the structure of this node in the Mail User Account Settings (see page 677) section.

Supported Operations

693

Request Samples
The following packet creates on a single domain two mail accounts with a minimum of settings:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>admin</name> <mailbox> <enabled>true</enabled> </mailbox> <password>12345</password> <password_type>crypt</password_type> <permissions> <cp_access>true</cp_access> </permissions> </mailname> <mailname> <name>techdept</name> <mailbox> <enabled>true</enabled> </mailbox> </mailname> </filter> </create> </mail> </packet>

To create multiple mail accounts on different domains within one packet, use multiple create nodes:
<packet version=1.4.2.0> <mail> <create> <filter> <domain_id>12</domain_id> <mailname> <name>admin</name> <mailbox> <enabled>true</enabled> </mailbox> <password>12345</password> <password_type>crypt<password_type> <permissions> <cp_access>true</cp_access> </permissions> </mailname> </filter> </create> <create> <filter> <domain_id>13</domain_id> <mailname>

694

Supported Operations <name>admin</name> <mailbox> <enabled>true</enabled> </mailbox> <password>qwerty123456</password> <password_type>plain<password_type> </mailname> </filter> </create> </mail> </packet>

Mail accounts can be created by Plesk Administrator or by Plesk clients. The packets are similar in both cases, except for Plesk clients can create mail accounts on their own domains only.

Response Packet Structure


The create node of the response packet is structured as follows:

The result node is required. It wraps the result of the requested create operation. Data type: operationresultType (common.xsd). The status node is required. It returns the execution status of the create operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns an error code when the create operation fails. Data type: unsignedInt. The errtext node is optional. It returns an error message if the create operation fails. Data type: string. The mailname node is optional. It is required if the create operation succeeds. Returns a collection of settings set for the mail account that has just been created. Data type: mailnameType (plesk_mailname.xsd). To see the structure of this node, refer to the Mail User Account Settings (see page 677) section.

Supported Operations

695

Response Samples
A positive response received from server after creating two mail accounts on the same domain looks as follows:
<packet version=1.4.2.0> <mail> <create> <result> <status>ok</status> <mailname> <name>techdept</name> </mailname> </result> <result> <status>ok</status> <mailname> <name>findept</name> </mailname> </result> </create> </mail> <output>c</output> </packet>

A negative response can look as follows:


<packet version=1.4.2.0> <mail> <create> <result> <status>error</status> <errcode>1015</errcode> <errtext>Object owner not found.</errtext> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </create> </mail> </packet>

The result blocks do not indicate creation of which mail accounts has failed. To distinguish between multiple requests, you can rely on the order they followed one another in the request packet.

696

Supported Operations

Modifying Mail Account Settings


Mail account settings can be modified either by Plesk Administrator or by Plesk client. These settings are as follows: Mail user access to his account through Plesk GUI Mail box size Mail box alias Mail user permissions Antivirus protection Mail group members (if an account acts as a mail group) Mail groups in which the mail account has membership Files stored in the account repository Automatic response messages Mail addresses to which all incoming correspondence will be redirected automatically

The update operation is presented by three sub-operations: add, remove, and set. All these sub-operations were designed for working with the lists of objects kept in mail accounts. The add sub-operation is a typical update operation. It means that all the setting specified in the packet will be added to a mail account, and the settings already existing will be kept unchanged. This sub-operation can be applied to any setting. The remove sub-operation is a typical delete operation. It means that all the setting specified in the packet will be removed from a mail account. The settings not mentioned in the packet will be kept unchanged. The set sub-operation is a hybrid (delete + update) operation. It means that all settings specified in the packet will replace all the settings already existing for the mail account.

In this section:
Request Packet Structure ..................................................................................697 Request Samples ..............................................................................................698 Response Packet Structure ...............................................................................701 Response Samples ............................................................................................702

Supported Operations

697

Request Packet Structure


A request XML packet updating mail account settings includes the update operation node:
<packet version=1.4.2.0> <mail> <update> </update> </mail> </packet>

The update node does not have a separate data type, it is nested within the MailTypeRequest complex type (mail_input.xsd). The update node has the following graphics representation:

The update operation breaks into three types of update: The add node is required. If specified, it adds the passed in settings to the mail account (all previously set settings are kept unchanged). Data type: none. The remove node is required. If specified, it removes the passed in settings from the specified mail account. Data type: none. The set node is required. If specified, it removes all previously set settings from the mail user account and sets the passed in settings anew. Data type: none. The filter node is required. It specifies the domain which mail accounts will be modified, and the settings of each account as well. Data type: mailnameFilterType (mail_input.xsd). See the structure of this node in the Filtering Issues (see page 690) section.

698

Supported Operations

Request Samples
Adding new mail account settings The following packet updates a mail account as follows: New email addresses are added to the mail group created on basis of this account.
<packet version=1.4.2.0> <mail> <update> <add> <filter> <domain_id>12</domain_id> <mailname> <name>admin</name> <mailgroup> <enabled>true</enabled> <address>techdept@advent.co.uk</address> <address>findept@advent.co.uk</address> <address>techgroup@advent.co.uk</address> </mailgroup> </mailname> <mailname> <name>webmaster</name> <mailgroup> <enabled>true</enabled> <address>bob@advent.co.uk</address> <address>ann@advent.co.uk</address> <address>nick@advent.co.uk</address> </mailgroup> </mailname> </filter> </add> </update> </mail> </packet>

To add new settings to email accounts that belong to different domains, use multiple create elements:
<packet version=1.4.2.0> <mail> <update> <add> <filter> <domain_id>12</domain_id> <mailname> <name>admin</name> <mailgroup> <enabled>true</enabled> <address>techdept@advent.co.uk</address> <address>findept@advent.co.uk</address> <address>techgroup@advent.co.uk</address> </mailgroup> </mailname> </filter> </add>

Supported Operations </update> <update> <add> <filter> <domain_id>13</domain_id> <mailname> <name>bfischer</name> <mailgroup> <enabled>true</enabled> <address>bob@techservice.co.uk</address> <address>ann@techservice.co.uk</address> <address>nick@techservice.co.uk</address> </mailgroup> </mailname> </filter> </add> </update> </mail> </packet>

699

Removing mail account settings The following packet removes several email addresses from mail groups created by the previous sample packet:
<packet version=1.4.2.0> <mail> <update> <remove> <filter> <domain_id>12</domain_id> <mailname> <name>admin</name> <mailgroup> <enabled>true</enabled> <address>techgroup@advent.co.uk</address> </mailgroup> </mailname> <mailname> <name>webmaster</name> <mailgroup> <enabled>true</enabled> <address>ann@techservice.co.uk</address> <address>nick@techservice.co.uk</address> </mailgroup> </mailname> </filter> </remove> </update> </mail> </packet>

The first mail group stores two addresses now (techdept@advent.co.uk and findept@advent.co.uk). The second mail group stores one address (bob@techservice.co.uk).

700

Supported Operations

Setting new mail account settings The following packet removes all email addresses from mail groups of the specified two email user accounts. After that the new addresses are added to the lists:
<packet version=1.4.2.0> <mail> <update> <set> <filter> <domain_id>12</domain_id> <mailname> <name>admin</name> <mailgroup> <enabled>true</enabled> <address>techgroup@advent.co.uk</address> <address>fingroup@advent.co.uk</address> </mailgroup> </mailname> <mailname> <name>webmaster</name> <mailgroup> <enabled>true</enabled> <address>ann@techservice.co.uk</address> <address>nick@techservice.co.uk</address> </mailgroup> </mailname> </filter> </set> </update> </mail> </packet>

Supported Operations

701

Response Packet Structure


The update node of the response packet is structured as follows:

The add node is required. It returns the result of the add sub-operation (the passedin settings are added to the mail account, all previously set settings are kept unchanged). Data type: none. The remove node is required. It returns the result of the remove sub-operation (the passed-in settings are removed from the mail account, other settings are kept unchanged). Data type: none. The set node is required. It returns the result of the set sub-operation (all previously set settings are removed, after which the passed-in settings are applied to the mail account). Data type: none. The result node is required. It wraps the result of the update operation. Data type: operationresultType (mail_output.xsd). The status node is required. It returns the execution status of the update operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns an error code when the update operation fails. Data type: unsignedInt. The errtext node is optional. It returns an error message if the update operation fails. Data type: string. The mailname node is optional. It is required if the update operation succeeds. Returns a collection of updated settings of the specified mail account(s). Data type: mailnameType (plesk_mailname.xsd). To see the structure of this node, refer to the Mail User Account Settings (see page 677) section.

702

Supported Operations

Response Samples
Here is a sample response received from server after the specified mail accounts are updated with new settings successfully:
<packet version=1.4.2.0> <mail> <update> <add> <result> <status>ok</status> <mailname> <name>admin</name> </mailname> </result> <result> <status>ok</status> <mailname> <name>webmaster</name> </mailname> </result> </add> </update> </mail> </packet>

The packets received after removing/resetting mail account settings have the similar structure. If the update operation on any mail account fails, a negative response packet looks as follows:
<packet version=1.4.2.0> <mail> <update> <add> <result> <status>error</status> <errcode>1015</errcode> <errtext>Object owner not found.</errtext> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <mailname> <name>techdept</name> </mailname> </result> </add> </update> </mail> </packet>

If the result blocks do not indicate what particular email account failed, you can rely on the order they followed one another in the request packet.

Supported Operations

703

Getting Mail Account Settings


Plesk Administrator can get settings of any mail account registered on any domain. Plesk clients are allowed to get settings of mail accounts registered on their own domains only. The settings are as follows: Mail account identifier, name, and alias Control panel access settings Mail box settings Automatic responses, redirects, stored files Mail group settings Mail user permissions

Use the get_info operation to retrieve domain settings.

In this section:
Request Packet Structure.................................................................................. 703 Request Samples .............................................................................................. 705 Response Packet Structure ............................................................................... 706 Response Samples ........................................................................................... 707

Request Packet Structure


A request XML packet getting a collection of mail account settings should include the get_info operation node:

<packet version=1.4.2.0> <mail> <get_info> </get_info> </mail> </packet>

704

Supported Operations

The get_info node does not have a separate type, it is nested within the MailTypeRequest complex type (mail_input.xsd). The get_info node has the following graphics representation:

The filter node is required. It holds a collection of data describing which mail account settings to retrieve. Data type: GetInfoAdvancedFilter (mail_input.xsd). The domain_id node is required. It specifies the identifier of the domain which mail accounts are requested. Data type: integer. The name node is optional. It specifies the name of the mail account. Data type: string. The cp_access node is optional. It indicates that control panel access settings of the specified mail account are requested. Data type: none. The mailbox node is optional. It indicates that mail box settings of the specified mail account are requested. Data type: none. The mailbox-usage node is optional. If it is present in the request packet, the amount of disk space used by a specific mailbox will be retrieved in the response packet. Data type: none. Note: This node is supported in API RPC 1.5.2.0 and later versions.

The redirect node is optional. It indicates that the list of redirects of the specified mail account is requested. Data type: none.

Supported Operations

705

The group node is optional. It indicates that the mail group settings of the specified mail account are requested. Data type: none. The groups node is optional. It indicates that the list of mail groups in which the given account has a membership is requested. Data type: none. The aliases node is optional. It indicates that the list of aliases of the given mail account is requested. Data type: none. The autoresponders node is optional. It indicates that the list of automatic-response objects of the given mail account is requested. Data type: none. The repository node is optional. It indicates that the list of files stored in the repository of the given mail account is requested. Data type: none. The repository_content node is optional. It indicates that the list of files and their contents stored in the repository of the given mail account is requested. Data type: none. The permissions node is optional. It indicates that a collection of permissions set for the given mail user is requested. Data type: none. This node is supported by API RPC 1.4.2.0 and later.

Request Samples
The following sample packet requests for information on two mail accounts belonging to the same domain:
<packet version=1.4.2.0> <mail> <get_info> <filter> <domain_id>12</domain_id> <name>techservice</name> <name>techknowledge</name> </filter> <cp_access/> <mailbox/> <aliases/> <permissions/> </get_info> </mail> </packet>

706

Supported Operations

To request information on mail accounts belonging to different domains, use multiple get_info sections:
<packet version=1.4.2.0> <mail> <get_info> <filter> <domain_id>12</domain_id> <name>techservice</name> <name>techknowledge</name> </filter> <cp_access/> <mailbox/> </get_info> <get_info> <filter> <domain_id>13</domain_id> <name>admin</name> </filter> <permissions/> </get_info> </mail> </packet>

Response Packet Structure


The get_info node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested get_info operation. It can be missing if some error occurs before the validation starts. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the get_info operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code if the get_info operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the get_info operation fails. Data type: string.

Supported Operations

707

The mailname node is required if the get_info operation succeeds. It contains a collection of mail account settings ordered in the request packet. Data type: mailnameType (plesk_mailname.xsd). See the structure of this node in the Mail Account Settings (see page 677) section.

Response Samples
A positive response that returns the requested information for the specified mail accounts can look as follows:
<packet version=1.4.2.0> <mail> <get_info> <result> <status>ok</status> <mailname> <name>techdept</name> <cp_access> <enabled>true</enabled> <access> <locale>EN-US</locale> <skin_id>11</skin_id> <multiply_login>true</multiply_login> <disable_lock_screen>false</disable_lock_screen> </access> </cp_access> </mailname> </result> <result> <status>ok</status> <mailname> <name>techknowledge</name> <cp_access> <enabled>false</enabled> <access> </access> </cp_access> </mailname> </result> </get_info> </mail> </packet>

708

Supported Operations

A negative response can look as follows:


<packet version=1.4.2.0> <mail> <get_info> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <mailname> <name>techknowledge</name> </mailname> </result> </get_info> </mail> </packet>

Deleting Mail Accounts


The remove operation is used to remove one to many mail accounts at one stroke, provided all these accounts refer to the same domain. Plesk Administrator can remove any mail account registered in Plesk, while a Plesk client can delete mail accounts referring to domains that belong to this Plesk client only.

In this section:
Request Packet Structure.................................................................................. 708 Request Samples .............................................................................................. 709 Response Packet Structure ............................................................................... 710 Response Samples ........................................................................................... 711

Request Packet Structure


A request XML packet that deletes mail accounts should include the remove operation node:
<packet version=1.4.2.0> <mail> <remove> </remove> </mail> </packet>

Supported Operations

709

The remove node does not have a separate type, it is nested within the MailTypeRequest type (mail_input.xsd). The remove node has the following graphics representation:

The filter node is required. It specifies what mail accounts should be removed. Data type: mailFilterType (mail_input.xsd). The domain_id node is required. It specifies the identifier of the domain which mail account (or several) will be deleted. Data type: integer. The name node is optional. It specifies the name of the mail account to be deleted. Data type: string.

Remarks To remove all mail accounts existing on a domain, include to your request packet filter rule containing only domain_id node.

Request Samples
The following packet deletes several mail accounts belonging to one domain:
<packet version=1.4.2.0> <mail> <remove> <filter> <domain_id>12</domain_id> <name>techdept</name> <name>techknowledge</name> <name>findept</name> <name>proddept</name> </filter> </remove> </mail> </packet>

710

Supported Operations

To delete several mail accounts belonging to different domains, use multiple remove sections:
<packet version=1.4.2.0> <mail> <remove> <filter> <domain_id>12</domain_id> <name>techdept</name> <name>techknowledge</name> </filter> </remove> <remove> <filter> <domain_id>13</domain_id> <name>findept</name> <name>proddept</name> </filter> </remove> </mail> </packet>

To delete all mail accounts from the specified domain, the following packet can be used:
<packet version=1.4.2.0> <mail> <remove> <filter> <domain_id>12</domain_id> </filter> </remove> </mail> </packet>

Response Packet Structure


The remove node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested remove operation. Data type: resultType (common.xsd).

Supported Operations

711

The status node is required. It returns the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Returns an error code when the remove operation fails. Data type: unsignedInt. The errtext node is optional. Returns an error message if the remove operation fails. Data type: string. The mailname node is required if the remove operation succeeds. It contains a settings of the mail account that has been deleted. Data type: mailnameType. See the structure of this node in the Mail User Account Settings (see page 677) section.

Response Samples
A positive response received from server after deleting particular mail accounts looks as follows:
<packet version=1.4.2.0> <mail> <remove> <result> <status>ok</status> <mailname> <name>techdept</name> </mailname> </result> <result> <status>ok</status> <mailname> <name>techknowledge</name> </mailname> </result> </set_prefs> </mail> </packet>

A negative response can look as follows:


<packet version=1.4.2.0> <mail> <remove> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <mailname> <name>techdept</name> </mailname> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <mailname> <name>techknowledge</name> </mailname> </result> </set_prefs></mail></packet>

712

Supported Operations

Enabling/Disabling Mail Service on Domain


Use the enable (disable) operation to enable (disable) mail service on a particular domain.

In this section:
Request Packet Structure.................................................................................. 712 Request Samples .............................................................................................. 713 Response Packet Structure ............................................................................... 715 Response Samples ........................................................................................... 716

Request Packet Structure


A request XML packet that enables mail service on the specified domain contains the enable operation node:
<packet version=1.4.2.0> <mail> <enable> </enable> </mail> </packet>

The enable node does not have a separate data type, it is nested within the MailTypeRequest type (mail_input.xsd). The enable node has the following graphics representation:

The domain_id node is required. It indicates the domain on which mail service should be turned on. Data type: integer.

A request XML packet that disables mail service on the specified domain contains the disable operation node:
<packet version=1.4.2.0> <mail> <disable> </disable> </mail> </packet>

Supported Operations

713

The disable node does not have a separate data type, it is nested within the MailTypeRequest complex type (mail_input.xsd). The disable node has the following graphics representation:

The domain_id node is required. It indicates the domain on which mail service should be turned off. Data type: it_type (integer).

Request Samples
The following request packet demonstrates how mail service can be enabled on multiple domains:
<packet version=1.4.2.0> <mail> <enable> <domain_id>11</domain_id> </enable> <enable> <domain_id>12</domain_id> </enable> <enable> <domain_id>15</domain_id> </enable> </mail> </packet>

To disable mail service on multiple domains, send the following request:


<packet version=1.4.2.0> <mail> <disable> <domain_id>11</domain_id> </disable> <disable> <domain_id>12</domain_id> </disable> <disable> <domain_id>15</domain_id> </disable> </mail> </packet>

714

Supported Operations

API RPC allows the use of both these operations within a single packet and within the same mail operator:
<packet version=1.4.2.0> <mail> <enable> <domain_id>11</domain_id> </enable> <disable> <domain_id>12</domain_id> </disable> </mail> </packet>

Supported Operations

715

Response Packet Structure


The enable node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested enable operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the enable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return an error code if the enable operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the enable operation fails. Data type: string.

The disable node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested disable operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the disable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return an error code if the disable operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the disable operation fails. Data type: string.

716

Supported Operations

Response Samples
If the mail service has been turned on the domain successfully, a positive response arrives from Plesk server:
<packet version=1.4.2.0> <mail> <enable> <result> <status>ok</status> </result> </enable> </mail> </packet>

A positive response for the disable operation looks similarly.

If the mail service has been turned on the multiple domains, a positive response from Plesk server looks as follows:
<packet version=1.4.2.0> <mail> <enable> <result> <status>ok</status> </result> <result> <status>ok</status> </result> <result> <status>ok</status> </result> </enable> </mail> </packet>

Supported Operations

717

The results will be returned in the order the enable node have been sent in the request packet. If the enable operation fails, a negative response packet looks as follows:
<packet version=1.4.2.0> <mail> <enable> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> <result> <status>ok</status> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </enable> </mail> </packet>

The results (both positive and negative) will be returned in the order the enable node have been sent in the request packet.

Setting Mail Service Preferences


Use the set_prefs operation to set mail service preferences on the specified domains.

In this section:
Request Packet Structure.................................................................................. 717 Request Samples .............................................................................................. 718 Response Packet Structure ............................................................................... 720 Response Samples ........................................................................................... 720

Request Packet Structure


A request XML packet setting mail service preferences for the specified domains includes the set_prefs operation node:
<packet version=1.4.2.0> <mail> <set_prefs> </set_prefs> </mail> </packet>

718

Supported Operations

The set_prefs node does not have a separate data type, it is nested within the MailTypeRequest type (mail_input.xsd). The set_prefs node has the following graphics representation:

The filter node is required. It specifies a list of domains on which mail service settings are modified. Data type: none. The domain_id node is optional. It specifies the identifier of the domain on which mail service settings are modified. Data type: integer. The prefs node is required. It specifies a collection of mail service preferences that will be set for the specified domains. Data type: MailPreferences. The structure of this node is described in the Mail Service Settings (see page 675) section.

Request Samples
Setting Mail Service Preferences under Plesk Administrator Plesk Administrator can set mail service preferences for all domains registered in Plesk. The following packet demonstrates how Plesk Administrator changes mail service settings the same way on three domains.
<packet version=1.4.2.0> <mail> <set_prefs> <filter> <domain_id>12</domain_id> <domain_id>14</domain_id> <domain_id>15</domain_id> </filter> <prefs> <nonexistent-user> <reject/> </nonexistent-user> <webmail>true</webmail> </prefs> </set_prefs> </mail> </packet>

To set different settings for different domains within a single packet, use multiple set_prefs elements:
<packet version=1.4.2.0> <mail> <set_prefs> <filter> <domain_id>12</domain_id> </filter> <prefs> <nonexistent-user> <reject/>

Supported Operations </nonexistent-user> <webmail>true</webmail> </prefs> </set_prefs> <set_prefs> <filter> <domain_id>13</domain_id> <domain_id>14</domain_id> </filter> <prefs> <nonexistent-user> <forward>techdept@advent.co.uk</forward> </nonexistent-user> <webmail>false</webmail> </prefs> </set_prefs> </mail> </packet>

719

If the filter is empty, the specified settings will be applied to all domains registered in Plesk:
<packet version=1.4.2.0> <mail> <set_prefs> <filter/> <prefs> <webmail>true</webmail> </prefs> </set_prefs> </mail> </packet>

Setting Email Service Settings under Plesk client All the use cases of the set_prefs operation node for Plesk clients are similar to those for Plesk Administrator. The only difference is that an empty filter means that the specified settings will be applied to all domains belonging to the Plesk client sending the packet:
<packet version=1.4.2.0> <mail> <set_prefs> <filter/> <prefs> <webmail>true</webmail> </prefs> </set_prefs> </mail> </packet>

720

Supported Operations

Response Packet Structure


The set_prefs node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested set_prefs operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the set_prefs operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return an error code if the set_prefs operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return an error message if the set_prefs operation fails. Data type: string. The domain_id node is optional. Returns the identifier of the domain on which mail service settings have been modified. Data type: integer.

Response Samples
A positive response received from Plesk server after mail service settings are modified looks as shown below. This packet returns the result of modifications applied to two domains.
<packet version=1.4.2.0> <mail> <set_prefs> <result> <status>ok</status> <domain_id>12</domain_id> </result> <result> <status>ok</status> <domain_id>13</domain_id> </result> </set_prefs> </mail> </packet>

Supported Operations

721

If the operation fails, a negative response can look as follows:


<packet version=1.4.2.0> <mail> <set_prefs> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <domain_id>12</domain_id> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <domain_id>13</domain_id> </result> </set_prefs> </mail> </packet>

Getting Mail Service Preferences


Use the set_prefs operation to retrieve mail service settings set for the specified domains.

In this section:
Request Packet Structure.................................................................................. 721 Request Samples .............................................................................................. 722 Response Packet Structure ............................................................................... 723 Response Samples ........................................................................................... 724

Request Packet Structure


A request XML packet that asks for mail service settings for a certain domain should include the get_prefs operation node:
<packet version=1.4.2.0> <mail> <get_prefs> </get_prefs> </mail> </packet>

722

Supported Operations

The get_prefs node does not have a separate type, it is nested within the MailTypeRequest type (mail_input.xsd). The get_prefs node has the following graphics representation:

The filter node is required. It holds a list of domains which mail service settings are requested. Data type: none. The domain_id node is optional. It specifies an identifier of the domain which mail service settings are requested. Data type: integer.

Request Samples
Getting Mail Service Settings under Plesk Administrator Plesk Administrator can get mail service preferences for all domains registered in Plesk. The following packet demonstrates how Plesk Administrator requests for mail service settings of three domains: To get the mail service settings set for particular domains, use the following packet:
<packet version=1.4.2.0> <mail> <get_prefs> <filter> <domain_id>12</domain_id> <domain_id>14</domain_id> <domain_id>15</domain_id> </filter> </get_prefs> </mail> </packet>

To request these settings for all domains registered in Plesk, the following packet must be used:
<packet version=1.4.2.0> <mail> <get_prefs> <filter/> </get_prefs> </mail> </packet>

Supported Operations

723

Getting Mail Service Settings under Plesk Client All the use cases of the get_prefs operation for Plesk clients are similar to those for Plesk Administrator, described above. The only difference is that an empty filter means that the specified settings will be retrieved from all domains belonging to Plesk client sending the packet:
<packet version=1.4.2.0> <mail> <get_prefs> <filter/> </get_prefs> </mail> </packet>

Response Packet Structure


The get_prefs node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested get_prefs operation. It can be missing if some error occurs before the validation starts. Data type: resultType (common.xsd). The status node is required. Returns the execution status of the get_prefs operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Returns an error code when the get_prefs operation fails. Data type: unsignedInt. The errtext node is optional. Returns an error message if the get_prefs operation fails. Data type: string. The domain_id node is optional. Returns the identifier of the domain which mail service settings are retrieved. Data type: integer. The prefs node is optional. Returns a collection of mail service preferences set for the specified domain. Data type: MailPreferences (plesk_mail.xsd). The structure of the node is described in the Mail Service Settings (see page 675) section.

724

Supported Operations

Response Samples
A positive response that returns mail service settings for two specified domains looks as follows:
<packet version=1.4.2.0> <mail> <get_prefs> <result> <status>error</status> <domain_id>12</domain_id> <prefs> <nonexistent-user> <reject/> </nonexistent-user> <webmail>true</webmail> </prefs> </result> <result> <status>error</status> <domain_id>13</domain_id> <prefs> <nonexistent-user> <forward>techdept@advent.co.uk</forward> </nonexistent-user> <webmail>true</webmail> </prefs> </result> </get_prefs> </mail> </packet>

If the operation fails, a negative response can look as follows:


<packet version=1.4.2.0> <mail> <get_prefs> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <domain_id>12</domain_id> </result> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> <domain_id>13</domain_id> </result> </get_prefs> </mail> </packet>

Supported Operations

725

Renaming Mail Accounts


Use the rename operation to rename a mail account.

In this section:
Request Packet Structure.................................................................................. 725 Request Samples .............................................................................................. 726 Response Packet Structure ............................................................................... 726 Response Samples ........................................................................................... 727

Request Packet Structure


A request XML packet setting a new name for an existing mail account should include the rename operation node:
<packet version=1.4.2.0> <mail> <rename> </rename> </mail> </packet>

The rename node does not have a separate type, it is nested within the MailTypeRequest type (mail_input.xsd). The rename node has the following graphics representation:

The domain_id node is required. It identifies the domain that owns the mail account. Data type: integer. The name node is required. It specifies the current name of the mail account. Data type: string. The new-name node is required. It specifies the new name for the mail account. Data type: string.

726

Supported Operations

Request Samples
The following request packet renames mail account existing on the domain with ID 11:
<packet version=1.4.2.0> <mail> <rename> <domain_id>11</domain_id> <name>admin</name> <new-name>administrator</new-name> </rename> </mail> </packet>

To rename multiple mail accounts with a single packet, use a separate rename section for each:
<packet version=1.4.2.0> <mail> <rename> <domain_id>11</domain_id> <name>admin</name> <new-name>administrator</new-name> </rename> <rename> <domain_id>11</domain_id> <name>common</name> <new-name>main</new-name> </rename> </mail> </packet>

Response Packet Structure


The rename node of the response packet is structured as follows:

The result node is optional. It wraps the result of the requested rename operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the rename operation. Data type: string. Allowed values: ok | error.

Supported Operations

727

The errcode node is optional. Returns an error code when the rename operation fails. Data type: unsignedInt. The errtext node is optional. Returns an error message if the rename operation fails. Data type: string.

Response Samples
After the specified mail account is renamed successfully, a positive response arrives from Plesk server:
<packet version=1.4.2.0> <mail> <rename> <result> <status>ok</status> </result> </rename> </mail> </packet>

If the request packet renames multiple accounts, the response packet will look as follows:
<packet version=1.4.2.0> <mail> <rename> <result> <status>ok</status> </result> </rename> <rename> <result> <status>ok</status> </result> </rename> </mail> </packet>

The packet will return the result for every filtered domain within a separate rename node. The results will follow one another in the order they have been sent in the request packet. If the operation fails, a negative response can look as follows:
<packet version=1.4.2.0> <mail> <rename> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </rename></mail></packet>

728

Supported Operations

Managing Mailing Lists


Operator: <maillist> XML Schema: maillist.xsd Plesk version: all versions API RPC version: 1.4.2.0 and higher Plesk user: Plesk Administrator, Plesk client Description The maillist operator is designed for managing mailing lists on domains. Each mailing list can be enabled or disabled. If it is disabled, the messages from mailing list owner will not be sent to subscribers. The mailing service (managing all mailing lists on a domain) can be activated or deactivated. If it is deactivated, all messages from all mailing list owners of a specified domain will not be sent to subscribers. Mailing lists are provided by the GNU Mailman software. Before using the operator, make sure that the specified software is installed on your Plesk server. Each mailing list should have unique name parameter. The e-mail address that is used for messages delivery to subscribers looks as follows: name@domain. The name of the mailing list cannot be changed.

In this section:
Filtering Issues .................................................................................................. 730 Adding Mailing List ............................................................................................ 732 Removing Mailing List ....................................................................................... 738 Adding Subscriber to Mailing List ...................................................................... 743 Retrieving Mailing Lists ..................................................................................... 748 Retrieving Subscribers' Info ............................................................................... 754 Removing Subscriber ........................................................................................ 759 Activating Mailing Lists Service ......................................................................... 763 Deactivating Mailing Lists Service ..................................................................... 769 Enabling Mailing List ......................................................................................... 774 Disabling Mailing List......................................................................................... 779 Retrieving Status of Mailing Lists Service .......................................................... 783

Supported Operations

729

Supported operations

ADD-LIST (see page 732) adds a new mailing list to the specified domain DEL-LIST (see page 738) deletes mailing lists using filtering rules GET-LIST (see page 748) retrieves mailing lists name and status using filtering rules ADD-MEMBER (see page 743) adds a new subscriber to the specified mailing list GET-MEMBERS (see page 754) retrieves the subscribers of the specified mailing lists DEL-MEMBERS (see page 759) removes a subscriber from the specified mailing lists ENABLE (see page 763) activates the mailing list service on the specified domains DISABLE (see page 769) deactivates the mailing list service on the specified domains ENABLE-LIST (see page 774) activates the specified mailing lists DISABLE-LIST (see page 779) deactivates the specified mailing lists GET-STATUS (see page 783) retrieves the status of the mailing service on the specified domain

730

Supported Operations

Filtering Issues
Filtering is the way the request XML packet indicates the object (one or several mailing lists or domains) to which an operation will be applied. The request XML filters objects using a special <filter> section. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

In this section:
MaillistFilterType ............................................................................................... 730 MaillistSimpleFilterType .................................................................................... 731 MaillistToggleFilterType .................................................................................... 732 filter-id Node ...................................................................................................... 732

MaillistFilterType
The MaillistFilterType filter is used in del-list, get-list, enable-list, disable-list operations to retrieve, remove, enable or disable mailing lists. For more information on the operations, refer to the Removing Mailing List (see page 738), Retrieving Mailing Lists (see page 748), Enabling Mailing List (see page 774), Disabling Mailing List (see page 779) sections. Data type:MaillistFilterType (maillist.xsd). The graphical representation of the filter node is as follows:

The id node is required. It specifies the mailing list ID in Plesk database. Data type: integer. The name node is required. It specifies the mailing list name. Data type: string. The domain-id node is required. It specifies the domain ID in Plesk database. Use this parameter to specify all mailing lists on the domain (specified by ID). Data type: integer.

Supported Operations

731

The domain-name node is required. It specifies the domain name. Use this parameter to specify all mailing lists on the domain (specified by name). Data type: string.

You can match multiple mailing lists using this filter as in the following example:
<filter> <domain-id>192</domain-id> <domain-id>19</domain-id> </filter>

Note: Use either id, name, domain-id, or domain-name parameters when creating a filtering rule. A packet containing a combination of id, domain-id, name, and domain-name parameters in a single filter node will be considered invalid by Plesk server.

MaillistSimpleFilterType
The MaillistSimpleFilterType filter is used in add-member, get-members, and del-member operations to add, retrieve, or remove mailing list subscribers. For more information on the operations, refer to the Adding Subscriber to Mailing List (see page 743), Retrieving Subscribers' Info (see page 754), Removing Subscriber (see page 759) sections. Data type:MaillistSimpleFilterType (maillist.xsd). The graphical representation of the filter node is as follows:

The list-id node is required. It specifies the mailing list ID in Plesk database. Data type: integer. The list-name node is required. It specifies the mailing list name. Data type: string.

You can match multiple mailing lists using this filter as in the following example:
<filter> <list-id>1</list-id> <list-id>4</list-id> </filter>

Note: Use either list-id, or list-name parameters when creating a filtering rule. A packet containing a combination of list-id and list-name parameters in a single filter node will be considered invalid by Plesk server.

732

Supported Operations

MaillistToggleFilterType
The MaillistToggleFilterType filter is used in enable, disable, and get-status operations to activate, deactivate, or retrieve status of a mailing list service on a specified domain. For more information on the operations, refer to the Activating Mailing Lists Service (see page 763), Deactivating Mailing Lists Service (see page 769), Retrieving Status of Mailing List Service (see page 783) sections. Data type:MaillistToggleFilterType (maillist.xsd). The graphical representation of the filter node is as follows:

The domain-id node is required. It specifies the domain ID in Plesk database. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string.

You can match multiple domains using this filter as in the following example:
<filter> <domain-name>example.com</domain-name> <domain-name>mydomain.com</domain-name> </filter>

Note: Use either domain-id, or domain-name parameters when creating a filtering rule. A packet containing a combination of domain-id and domain-name parameters in a single filter node will be considered invalid by Plesk server.

filter-id Node

If an operation uses filters in a request packet, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet. mailing list ID mailing list name domain ID domain name

It is done to trace the request parameters in case of error. Data type: anySimpleType. All operations except for the add-list possess the filter-id node in the response packet.

Supported Operations

733

Adding Mailing List


Use the add-list operation to add a new mailing list.

In this section:
Request Packet Structure.................................................................................. 734 Request Samples .............................................................................................. 735 Response Packet Structure ............................................................................... 736 Response Samples ........................................................................................... 737

734

Supported Operations

Request Packet Structure


A request XML packet adding a mailing list to Plesk database includes the add-list operation node:
<packet version="1.4.2.0"> <maillist> <add-list> ... </add-list> </maillist> </packet>

The add-list node is presented by the MaillistAddListInputType type (maillist.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain ID in Plesk database. Data type: integer. The name node is required. It specifies the name of the mailing list. Data type: string. The password node is required. It specifies the mailing list administrator's password. Data type: string. The admin-email node is required. It specifies the mailing list administrator's e-mail address. All information on the mailing list management is sent to this e-mail address. Data type: string. The notify node is optional. Specifies if a notification of the mailing list creation will be sent to the administrator. Data type: boolean.

Remarks You can add multiple mailing lists in a single packet. Add as many add-list operations as the number of mailing lists to be added.
<add-list> </add-list> <add-list> </add-list>

Supported Operations

735

Request Samples
Adding a single mailing list This packet adds mailing list MyMailer to the domain specified by ID 45.
<packet version="1.4.2.0"> <maillist> <add-list> <domain-id>45</domain-id> <name>MyMailer</name> <password>hello</password> <admin-email>admin@mydomain.com</admin-email> </add-list> </maillist> </packet>

Adding multiple mailing lists This packet adds mailing lists MyMailer and SubscribeMe to the domain specified by ID 45.
<packet version="1.4.2.0"> <maillist> <add-list> <domain-id>45</domain-id> <name>MyMailer</name> <password>hello</password> <admin-email>admin@mydomain.com</admin-email> </add-list> <add-list> <domain-id>45</domain-id> <name>SubscribeMe</name> <password>123456</password> <admin-email>admin@mydomain.com</admin-email> </add-list> </maillist> </packet>

736

Supported Operations

Response Packet Structure


The add-list node of the output XML packet is presented by type MaillistAddOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultType (common.xsd). The status node is required. It specifies the execution status of the add-list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add-list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add-list operation fails. Data type: string. The id node is optional. It returns the mailing list ID in Plesk database if the operation succeeds. Data type: integer.

Supported Operations

737

Response Samples
Adding a single mailing list This request packet adds mailing list MyMailer to the domain specified by ID 45.
<packet version="1.4.2.0"> <maillist> <add-list> <domain-id>45</domain-id> <name>MyMailer</name> <password>hello</password> <admin-email>admin@mydomain.com</admin-email> </add-list> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <add-list> <result> <status>ok</status> <id>133</id> </result> </add-list> </maillist> </packet>

If the Mailman software is not installed on the server, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <add-list> <result> <status>error</status> <errcode>1031</errcode> <errtext>Component is not configured on server</errtext> </result> </add-list> </maillist> </packet>

738

Supported Operations

Adding multiple mailing lists This request packet adds mailing lists MyMailer and SubscribeMe to the domain specified by ID 45.
<packet version="1.4.2.0"> <maillist> <add-list> <domain-id>45</domain-id> <name>MyMailer</name> <password>hello</password> <admin-email>admin@mydomain.com</admin-email> </add-list> <add-list> <domain-id>45</domain-id> <name>SubscribeMe</name> <password>123456</password> <admin-email>admin@mydomain.com</admin-email> </add-list> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <add-list> <result> <status>ok</status> <id>133</id> </result> </add-list> <add-list> <result> <status>ok</status> <id>134</id> </result> </add-list> </maillist> </packet>

Supported Operations

739

Removing Mailing List


Use the del-list operation to remove mailing lists. Use filters to specify mailing lists by name, ID, domain ID, or domain name. For information on filters, refer to Filtering Issues (see page 730) section.

In this section:
Request Packet Structure.................................................................................. 739 Request Samples .............................................................................................. 740 Response Packet Structure ............................................................................... 741 Response Samples ........................................................................................... 742

Request Packet Structure


A request XML packet removing a mailing list from Plesk database includes the del-list operation node:
<packet version="1.4.2.0"> <maillist> <del-list> ... </del-list> </maillist> </packet>

The del-list node is presented by the MaillistDelListInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 730) section. Data type: MaillistFilterType (maillist.xsd).

Remarks You can remove mailing lists using different filtering rules in a single packet. Add as many del-list operations as the number of different filtering rules to be applied.
<del-list> </del-list> <del-list> </del-list>

740

Supported Operations

Request Samples
Removing a single mailing list This packet removes mailing list MyMailer.
<packet version="1.4.2.0"> <maillist> <del-list> <filter> <name>MyMailer</name> </filter> </del-list> </maillist> </packet>

Removing multiple mailing lists This packet removes mailing lists MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <del-list> <filter> <name>MyMailer</name> <name>SubscribeMe</name> </filter> </del-list> </maillist> </packet>

This packet removes all mailing lists from domains Mydomain.com and My2domain.com.
<packet version="1.4.2.0"> <maillist> <del-list> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </del-list> </maillist> </packet>

Supported Operations

741

This packet removes all mailing lists from domain Mydomain.com and the domain specified by ID 7.
<packet version="1.4.2.0"> <maillist> <del-list> <filter> <domain-name>Mydomain.com</domain-name> </filter> </del-list> <del-list> <filter> <domain-id>7</domain-id> </filter> </del-list> </maillist> </packet>

Response Packet Structure


The del-list node of the output XML packet is presented by type MaillistDelOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the del-list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the del-list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the del-list operation fails. Data type: string.

742

Supported Operations

The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. It returns the mailing list ID in Plesk database if the operation succeeds. Data type: integer.

Response Samples
Removing a single mailing list This request packet removes mailing list MyMailer.
<packet version="1.4.2.0"> <maillist> <del-list> <filter> <name>MyMailer</name> </filter> </del-list> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <del-list> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>13</id> </result> </del-list> </maillist> </packet>

If mailing list MyMailer was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <maillist> <del-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Maillist does not exist</errtext> <filter-id>MyMailer</filter-id> </result> </del-list> </maillist> </packet>

Supported Operations

743

Removing multiple mailing lists This request packet removes all mailing lists from domain Mydomain.com.
<packet version="1.4.2.0"> <maillist> <del-list> <filter> <domain-name>Mydomain.com</domain-name> </filter> </del-list> </maillist> </packet>

If three mailing lists were removed from the server, a server response can look as follows:
<packet version="1.4.2.0"> <maillist> <del-list> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <id>13</id> </result> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <id>18</id> </result> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <id>23</id> </result> </del-list> </maillist> </packet>

744

Supported Operations

Adding Subscriber to Mailing List


Use the add-member operation to add a new subscriber to a mailing list specified by name or ID.

In this section:
Request Packet Structure.................................................................................. 744 Request Samples .............................................................................................. 745 Response Packet Structure ............................................................................... 746 Response Samples ........................................................................................... 746

Request Packet Structure


A request XML packet adding a subscriber includes the add-member operation node:
<packet version="1.4.2.0"> <maillist> <add-member> ... </add-member> </maillist> </packet>

The add-member node is presented by the MaillistAddMemberInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. You can subscribe a person specified by id to multiple mailing lists in a single packet. For information on this filter, refer to the Filtering Issues (see page 731) section. Data type: MaillistSimpleFilterType (maillist.xsd). The id node is required. It specifies the subscriber's e-mail address. Data type: emailType (common.xsd).

Supported Operations

745

Remarks You can add multiple subscribers to a mailing list using different filtering rules in a single packet. Add as many add-member operations as the number of different filtering rules to be applied.
<add-member> </add-member> <add-member> </add-member>

Request Samples
Adding a subscriber This packet adds the subscriber with e-mail address mymail@mydomain.com to mailing list MyMailer.
<packet version="1.4.2.0"> <maillist> <add-member> <filter> <list-name>MyMailer</list-name> </filter> <id>mymail@mydomain.com</id> </add-member> </maillist> </packet>

Adding multiple mailing lists This packet adds the subscriber with e-mail address mymail@mydomain.com to mailing lists MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <add-member> <filter> <list-name>MyMailer</list-name> <list-name>SubscribeMe</list-name> </filter> <id>mymail@mydomain.com</id> </add-member> </maillist> </packet>

746

Supported Operations

Response Packet Structure


The add-member node of the output XML packet is presented by type MaillistAddMemberOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: MaillistMemberResultType (maillist.xsd). The status node is required. It specifies the execution status of the add-member operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add-member operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add-member operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. It returns the subscriber's email address if the operation succeeds. Data type: emailType (common.xsd).

Supported Operations

747

Response Samples
Adding a subscriber This request packet adds the subscriber with e-mail address mymail@mydomain.com to mailing list MyMailer.
<packet version="1.4.2.0"> <maillist> <add-member> <filter> <list-name>MyMailer</list-name> </filter> <id>mymail@mydomain.com</id> </add-member> </maillist> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <maillist> <add-member> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>mymail@mydomain.com</id> </result> </add-member> </maillist> </packet>

If the mailing list was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <add-member> <result> <status>error</status> <errcode>1015</errcode> <errtext>Mailing list does not exist</errtext> <filter-id>MyMailer</filter-id> </result> </add-member> </maillist> </packet>

748

Supported Operations

Adding subscribers to multiple mailing lists This request packet adds the subscriber with e-mail address mymail@mydomain.com to mailing lists MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <add-member> <filter> <list-name>MyMailer</list-name> <list-name>SubscribeMe</list-name> </filter> <id>mymail@mydomain.com</id> </add-member> </maillist> </packet>

The positive response looks as follows:


<packet version="1.4.2.0"> <maillist> <add-member> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>mymail@mydomain.com</id> </result> <result> <status>ok</status> <filter-id>SubscribeMe</filter-id> <id>mymail@mydomain.com</id> </result> </add-member> </maillist> </packet>

Supported Operations

749

Retrieving Mailing Lists


Use the get-list operation to retrieve preferences of specified mailing lists. Use filters to specify mailing lists by name, ID, domain ID, or domain name. For information on filters, refer to the Filtering Issues (see page 730) section.

In this section:
Request Packet Structure.................................................................................. 749 Request Samples .............................................................................................. 750 Response Packet Structure ............................................................................... 751 Response Samples ........................................................................................... 752

Request Packet Structure


A request XML packet retrieving a mailing list preferences includes the get-list operation node:
<packet version="1.4.2.0"> <maillist> <get-list> ... </get-list> </maillist> </packet>

The get-list node is presented by the MaillistGetListInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 730) section. Data type: MaillistFilterType (maillist.xsd).

Remarks You can retrieve parameters of multiple mailing lists using different filtering rules in a single packet. Add as many get-list operations as the number of different filtering rules to be applied.
<get-list> </get-list> <get-list> </get-list>

750

Supported Operations

Request Samples
Retrieving information on a single mailing list This packet retrieves preferences of the mailing list called MyMailer.
<packet version="1.4.2.0"> <maillist> <get-list> <filter> <name>MyMailer</name> </filter> </get-list> </maillist> </packet>

Retrieving information on multiple mailing lists This packet retrieves preferences of the mailing lists called MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <get-list> <filter> <name>MyMailer</name> <name>SubscribeMe</name> </filter> </get-list> </maillist> </packet>

This packet retrieves preferences of all mailing lists on domains Mydomain.com and My2domain.com.
<packet version="1.4.2.0"> <maillist> <get-list> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </get-list> </maillist> </packet>

Supported Operations

751

This packet retrieves preferences of all mailing lists on domain Mydomain.com and the domain specified by ID 7.
<packet version="1.4.2.0"> <maillist> <get-list> <filter> <domain-name>Mydomain.com</domain-name> </filter> </get-list> <get-list> <filter> <domain-id>7</domain-id> </filter> </get-list> </maillist> </packet>

Response Packet Structure


The get-list node of the output XML packet is presented by type MaillistGetListOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-list operation. Data type: string. Allowed values: ok | error.

752

Supported Operations

The errcode node is optional. Is returns the error code if the get-list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-list operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. It returns ID of the mailing list in Plesk database if the operation succeeds. Data type: integer. The name node is optional. It is required if the operation succeeds. It returns the name of the mailing list. Data type: string. The list-status is optional. It is required if the operation succeeds. It returns the status of the mailing list. Data type: boolean.

Response Samples
Retrieving information on a single mailing list This request packet retrieves preferences of the mailing list called MyMailer.
<packet version="1.4.2.0"> <maillist> <get-list> <filter> <name>MyMailer</name> </filter> </get-list> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <get-list> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>2</id> <name>MyMailer</name> <list-status>false</list-status> </result> </get-list> </maillist> </packet>

Supported Operations

753

If mailing list MyMailer was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <maillist> <get-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Maillist does not exist</errtext> <filter-id>MyMailer</filter-id> </result> </get-list> </maillist> </packet>

Retrieving information on multiple mailing lists This request packet retrieves preferences of all mailing lists on the domains with ID 1 and ID 21.
<packet version="1.4.2.0"> <maillist> <get-list> <filter> <domain-id>1</domain-id> <domain-id>21</domain-id> </filter> </get-list> </maillist> </packet>

If the domain with ID 21 was not found on the server, and the domain with ID 1 has two active mailing lists, a response from the server can look as follows:
<packet version="1.4.2.0"> <maillist> <get-list> <result> <status>ok</status> <filter-id>1</filter-id> <id>12</id> <name>MailerOne</name> <list-status>true</list-status> </result> <result> <status>ok</status> <filter-id>1</filter-id> <id>17</id> <name>MailerTwo</name> <list-status>true</list-status> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Domain does not exist</errtext> <filter-id>21</filter-id> </result></get-list></maillist></packet>

754

Supported Operations

Retrieving Subscribers' Info


Use the get-members to retrieve e-mail addresses of people who were subscribed to a specified mailing list.

In this section:
Request Packet Structure.................................................................................. 754 Request Samples .............................................................................................. 755 Response Packet Structure ............................................................................... 756 Response Samples ........................................................................................... 757

Request Packet Structure


A request XML packet retrieving info on subscribers of a mailing list includes the getmembers operation node:
<packet version="1.4.2.0"> <maillist> <get-members> ... </get-members> </maillist> </packet>

The get-members node is presented by the MaillistDelListInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 731) section. Data type: MaillistSimpleFilterType (maillist.xsd).

Remarks You can retrieve info on subscribers of multiple mailing lists using different filtering rules in a single packet. Add as many get-members operations as the number of different filtering rules to be applied.
<get-members> </get-members> <get-members> </get-members>

Supported Operations

755

Request Samples
Retrieving information on subscribers of a single mailing list This packet retrieves info on subscribers of the mailing list called MyMailer.
<packet version="1.4.2.0"> <maillist> <get-members> <filter> <list-name>MyMailer</list-name> </filter> </get-members> </maillist> </packet>

Retrieving information on subscribers of multiple mailing lists This packet retrieves info on subscribers of the mailing lists called MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <get-members> <filter> <name>MyMailer</name> <name>SubscribeMe</name> </filter> </get-members> </maillist> </packet>

This packet retrieves info on subscribers of the mailing list specified by ID 14, and mailing lists called MyList and SubscriptionList.
<packet version="1.4.2.0"> <maillist> <get-members> <filter> <list-id>14</list-id> </filter> </get-members> <get-members> <filter> <list-name>MyList</list-name> <list-name>SubscriptionList</list-name> </filter> </get-members> </maillist> </packet>

756

Supported Operations

Response Packet Structure


The get-members node of the output XML packet is presented by type MaillistGetMemberOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: GetMemberResultFilterType (maillist.xsd). The status node is required. It specifies the execution status of the get-members operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-members operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-members operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. It returns the subscriber's e-mail address if the operation succeeds. Data type: emailType (common.xsd).

Supported Operations

757

Response Samples
Retrieving information on subscribers of a single mailing list This request packet retrieves info on subscribers of the mailing list called MyMailer.
<packet version="1.4.2.0"> <maillist> <get-members> <filter> <list-name>MyMailer</list-name> </filter> </get-members> </maillist> </packet>

If two subscribers to MyMailer were found, a response from the server can look as follows:
<packet version="1.4.2.0"> <maillist> <get-members> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>mymail@mydomain.com</id> </result> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>subscr@mydomain.com</id> </result> </get-members> </maillist> </packet>

If the mailing list was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <get-members> <result> <status>error</status> <errcode>1015</errcode> <errtext>Mailing list does not exist</errtext> <filter-id>MyMailer</filter-id> </result> </get-members> </maillist> </packet>

758

Supported Operations

Retrieving information on subscribers of multiple mailing lists This request packet retrieves info on subscribers of the mailing list specified by ID 14 and mailing lists called MyList and SubscriptionList.
<packet version="1.4.2.0"> <maillist> <get-members> <filter> <list-id>14</list-id> </filter> </get-members> <get-members> <filter> <list-name>MyList</list-name> <list-name>SubscriptionList</list-name> </filter> </get-members> </maillist> </packet>

If each of MyList and SubscriptionList mailing lists have one subscriber, and the mailing list with ID 14 was not found on the server, a response can look as follows:
<packet version="1.4.2.0"> <maillist> <get-members> <result> <status>error</status> <errcode>1015</errcode> <errtext>Mailing list does not exist</errtext> <filter-id>MyMailer</filter-id> </result> </get-members> <get-members> <result> <status>ok</status> <filter-id>MyList</filter-id> <id>mymail@mydomain.com</id> </result> <result> <status>ok</status> <filter-id>SubscriptionList</filter-id> <id>subscr@mydomain.com</id> </result> </get-members> </maillist> </packet>

Supported Operations

759

Removing Subscriber
Use the del-member to remove a subscriber from specified mailing lists.

In this section:
Request Packet Structure.................................................................................. 759 Request Samples .............................................................................................. 760 Response Packet Structure ............................................................................... 761 Response Samples ........................................................................................... 762

Request Packet Structure


A request XML packet removing a subscriber from the specified mailing lists includes the del-member operation node:
<packet version="1.4.2.0"> <maillist> <del-member> ... </del-member> </maillist> </packet>

The add-member node is presented by the MaillistAddMemberInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. You can remove a person specified by id from multiple mailing lists in a single packet. For information on this filter, refer to the Filtering Issues (see page 731) section. Data type: MaillistSimpleFilterType (maillist.xsd). The id node is required. It specifies the subscriber's e-mail address. Data type: emailType (common.xsd).

760

Supported Operations

Remarks You can delete a subscriber from multiple mailing lists using different filtering rules in a single packet. Add as many del-member operations as the number of different filtering rules to be applied.
<del-member> </del-member> <del-member> </del-member>

Request Samples
Removing a subscriber from a single mailing list This packet removes the subscriber with e-mail address mymail@mydomain.com from mailing list MyMailer.
<packet version="1.4.2.0"> <maillist> <del-member> <filter> <list-name>MyMailer</list-name> </filter> <id>mymail@mydomain.com</id> </del-member> </maillist> </packet>

Removing a subscriber from multiple mailing lists This packet removes the subscriber with e-mail address mymail@mydomain.com from mailing lists MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <del-member> <filter> <list-name>MyMailer</list-name> <list-name>SubscribeMe</list-name> </filter> <id>mymail@mydomain.com</id> </del-member> </maillist> </packet>

Supported Operations

761

Response Packet Structure


The del-member node of the output XML packet is presented by type MaillistDelMemberOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: MaillistMemberResultType (maillist.xsd). The status node is required. It specifies the execution status of the del-member operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the del-member operation fails. Data type: integer. The errtext node is optional. It returns the error message if the del-member operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. It returns the subscriber's e-mail address if the operation succeeds. Data type: emailType (common.xsd).

762

Supported Operations

Response Samples
Removing a subscriber from a single mailing list This request packet removes the subscriber with e-mail address mymail@mydomain.com from mailing list MyMailer.
<packet version="1.4.2.0"> <maillist> <del-member> <filter> <list-name>MyMailer</list-name> </filter> <id>mymail@mydomain.com</id> </del-member> </maillist> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <maillist> <del-member> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>mymail@mydomain.com</id> </result> <result> </del-member> </maillist> </packet>

If the subscriber was not subscribed to MyMailer, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <get-members> <result> <status>error</status> <errcode>1023</errcode> <errtext>Member is not subscribed to mailing list</errtext> <filter-id>MyMailer</filter-id> </result> </get-members> </maillist> </packet>

Supported Operations

763

Removing a subscriber from multiple mailing lists

This request packet removes the subscriber with e-mail address mymail@mydomain.com from mailing lists MyMailer and SubscribeMe.
<packet version="1.4.2.0"> <maillist> <del-member> <filter> <list-name>MyMailer</list-name> <list-name>SubscribeMe</list-name> </filter> <id>mymail@mydomain.com</id> </del-member> </maillist> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <maillist> <del-member> <result> <status>ok</status> <filter-id>MyMailer</filter-id> <id>mymail@mydomain.com</id> </result> <result> <status>ok</status> <filter-id>SubscribeMe</filter-id> <id>mymail@mydomain.com</id> </result> </del-member> </maillist> </packet>

764

Supported Operations

Activating Mailing Lists Service


Use the enable operation to activate mailing lists service on a specified domain.

In this section:
Request Packet Structure.................................................................................. 764 Request Samples .............................................................................................. 765 Response Packet Structure ............................................................................... 766 Response Samples ........................................................................................... 767

Request Packet Structure


A request XML packet activating a mailing lists service includes the enable operation node:
<packet version="1.4.2.0"> <maillist> <enable> ... </enable> </maillist> </packet>

The enable node is presented by the MaillistEnableInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 732) section. Data type: MaillistToggleFilterType (maillist.xsd). The domain-id node is required. It specifies the ID of the domain address, on which the mailing service is to be enabled. Data type: integer. The domain-name node is required. It specifies the name of the domain address, on which the mailing service is to be enabled. Data type: integer.

Supported Operations

765

Remarks You can activate mailing lists service on multiple domains using different filtering rules in a single packet. Add as many enable operations as the number of different filtering rules to be applied.
<enable> </enable> <enable> </enable>

Request Samples
Activating mailing lists service on a single domain This packet activates the mailing lists service on the domain called Mydomain.com.
<packet version="1.4.2.0"> <maillist> <enable> <filter> <domain-name>Mydomain.com</domain-name> </filter> </enable> </maillist> </packet>

Activating mailing lists service on multiple domains This packet activates mailing lists service on Mydomain.com and My2domain.com domains.
<packet version="1.4.2.0"> <maillist> <enable> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </enable> </maillist> </packet>

766

Supported Operations

This packet activates mailing lists service on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <enable> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </enable> <enable> <filter> <domain-id>6</domain-id> </filter> </enable> </maillist> </packet>

Response Packet Structure


The enable node of the output XML packet is presented by type MaillistEnableOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the enable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the enable operation fails. Data type: integer.

Supported Operations

767

The errtext node is optional. It returns the error message if the enable operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. This node does not contain any data for this operation. Data type: integer.

Response Samples
Activating mailing lists service on a single domain This request packet activates the mailing lists service on the domain called Mydomain.com.
<packet version="1.4.2.0"> <maillist> <enable> <filter> <domain-name>Mydomain.com</domain-name> </filter> </enable> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <enable> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> </result> </enable> </maillist> </packet>

If the domain was not found on the server, the result looks as follows:
<packet version="1.4.2.0"> <maillist> <enable> <result> <status>error</status> <status>1015</status> <status>Domain does not exist</status> <filter-id>Mydomain.com</filter-id> </result> </enable> </maillist> </packet>

768

Supported Operations

Enabling mailing lists service on multiple domains This request packet activates mailing lists service on the domains Mydomain.com, My2domain.com, and on the domain specified by ID 5.
<packet version="1.4.2.0"> <maillist> <enable> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </enable> <enable> <filter> <domain-id>5</domain-id> </filter> </enable> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <enable> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> </result> <result> <status>ok</status> <filter-id>My2domain.com</filter-id> </result> </enable> <enable> <result> <status>ok</status> <filter-id>5</filter-id> </result> </enable> </maillist> </packet>

Supported Operations

769

Deactivating Mailing Lists Service


Use the disable operation to deactivate mailing lists service on a specified domain.

In this section:
Request Packet Structure.................................................................................. 769 Request Samples .............................................................................................. 770 Response Packet Structure ............................................................................... 771 Response Samples ........................................................................................... 772

Request Packet Structure


A request XML packet deactivating a mailing lists service includes the disable operation node:
<packet version="1.4.2.0"> <maillist> <disable> ... </disable> </maillist> </packet>

The disable node is presented by the MaillistDisableInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 732) section. Data type: MaillistToggleFilterType (maillist.xsd). The domain-id node is required. It specifies the ID of the domain address, on which the mailing service is to be disabled. Data type: integer. The domain-name node is required. It specifies the name of the domain address, on which the mailing service is to be disabled. Data type: integer.

770

Supported Operations

Remarks You can deactivate mailing lists service on multiple domains using different filtering rules in a single packet. Add as many disable operations as the number of different filtering rules to be applied.
<disable> </disable> <disable> </disable>

Request Samples
Deactivating mailing lists service on a single domain This packet deactivates the mailing lists service on the domain called Mydomain.com.
<packet version="1.4.2.0"> <maillist> <disable> <filter> <domain-name>Mydomain.com</domain-name> </filter> </disable> </maillist> </packet>

Deactivating mailing lists service on multiple domains This packet deactivates mailing lists service on Mydomain.com and My2domain.com domains.
<packet version="1.4.2.0"> <maillist> <disable> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </disable> </maillist> </packet>

Supported Operations

771

This packet deactivates mailing lists service on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <disable> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </disable> <disable> <filter> <domain-id>6</domain-id> </filter> </disable> </maillist> </packet>

Response Packet Structure


The disable node of the output XML packet is presented by type MaillistDisableOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the disable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the disable operation fails. Data type: integer.

772

Supported Operations

The errtext node is optional. It returns the error message if the disable operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. This node does not contain any data for this operation. Data type: integer.

Response Samples
Deactivating mailing lists service on a single domain This request packet deactivates the mailing lists service on the domain called Mydomain.com.
<packet version="1.4.2.0"> <maillist> <disable> <filter> <domain-name>Mydomain.com</domain-name> </filter> </disable> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <disable> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> </result> </disable> </maillist> </packet>

If the domain was not found on the server, the result looks as follows:
<packet version="1.4.2.0"> <maillist> <disable> <result> <status>error</status> <status>1015</status> <status>Domain does not exist</status> <filter-id>Mydomain.com</filter-id> </result> </disable> </maillist> </packet>

Supported Operations

773

Deactivating mailing lists service on multiple domains This request packet deactivates mailing list service on the domains Mydomain.com, My2domain.com, and on the domain specified by ID 5.
<packet version="1.4.2.0"> <maillist> <disable> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </disable> <disable> <filter> <domain-id>5</domain-id> </filter> </disable> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <disable> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> </result> <result> <status>ok</status> <filter-id>My2domain.com</filter-id> </result> </disable> <disable> <result> <status>ok</status> <filter-id>5</filter-id> </result> </disable> </maillist> </packet>

774

Supported Operations

Enabling Mailing List


Use the enable-list operation to enable mailing lists specified by name, ID, domain name, or domain ID.

In this section:
Request Packet Structure.................................................................................. 774 Request Samples .............................................................................................. 775 Response Packet Structure ............................................................................... 776 Response Samples ........................................................................................... 777

Request Packet Structure


A request XML packet enabling mailing lists includes the enable-list operation node:
<packet version="1.4.2.0"> <maillist> <enable-list> ... </enable-list> </maillist> </packet>

The enable-list node is presented by the MaillistEnableListInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 730) section. Data type: MaillistFilterType (maillist.xsd).

Remarks You can enable multiple mailing lists using different filtering rules in a single packet. Add as many enable-list operations as the number of different filtering rules to be applied.
<enable-list> </enable-list> <enable-list> </enable-list>

Supported Operations

775

Request Samples
Enabling a single mailing list This packet enables mailing list Mylist.
<packet version="1.4.2.0"> <maillist> <enable-list> <filter> <name>Mylist</name> </filter> </enable-list> </maillist> </packet>

Enabling multiple mailing lists This packet enables mailing lists on Mydomain.com domain.
<packet version="1.4.2.0"> <maillist> <enable-list> <filter> <domain-name>Mydomain.com</domain-name> </filter> </enable-list> </maillist> </packet>

This packet enables mailing lists on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <enable-list> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </enable-list> <enable-list> <filter> <domain-id>6</domain-id> </filter> </enable-list> </maillist> </packet>

776

Supported Operations

Response Packet Structure


The enable-list node of the output XML packet is presented by type MaillistEnableListOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the enable-list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the enable-list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the enable-list operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. It returns ID of the mailing list if the operation succeeds. Data type: integer.

Supported Operations

777

Response Samples
Enabling a single mailing list This request packet enables mailing list Mylist.
<packet version="1.4.2.0"> <maillist> <enable-list> <filter> <name>Mylist</name> </filter> </enable-list> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <enable-list> <result> <status>ok</status> <filter-id>Mylist</filter-id> <id>5</id> </result> </enable-list> </maillist> </packet>

If the mailing list was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <enable-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Mailing list does not exist</errtext> <filter-id>Mylist</filter-id> </result> </enable-list> </maillist> </packet>

778

Supported Operations

Enabling multiple mailing lists This request packet enables mailing lists on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <enable-list> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </enable-list> <enable-list> <filter> <domain-id>6</domain-id> </filter> </enable-list> </maillist> </packet>

If My2domain.com domain was not found, Mydomain.com domain contains two mailing lists (specified by ID 1 and ID 2), the domain with ID 6 contains one mailing list (specified by ID 7), the response looks as follows:
<packet version="1.4.2.0"> <maillist> <enable-list> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <id>1</id> </result> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <id>2</id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>My2domain.com</filter-id> </result> </enable-list> <enable-list> <result> <status>ok</status> <filter-id>6</filter-id> <id>7</id> </result> </enable-list> </maillist> </packet>

Supported Operations

779

Disabling Mailing List


Use the disable-list operation to disable mailing lists specified by name, ID, domain name, or domain ID.

In this section:
Request Packet Structure.................................................................................. 779 Request Samples .............................................................................................. 780 Response Packet Structure ............................................................................... 781 Response Samples ........................................................................................... 782

Request Packet Structure


A request XML packet disabling mailing lists includes the disable-list operation node:
<packet version="1.4.2.0"> <maillist> <disable-list> ... </disable-list> </maillist> </packet>

The disable-list node is presented by the MaillistDisableListInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 730) section. Data type: MaillistFilterType (maillist.xsd).

Remarks You can disable multiple mailing lists using different filtering rules in a single packet. Add as many disable-list operations as the number of different filtering rules to be applied.
<disable-list> </disable-list> <disable-list> </disable-list>

780

Supported Operations

Request Samples
Disabling a single mailing list This packet disables mailing list Mylist.
<packet version="1.4.2.0"> <maillist> <disable-list> <filter> <name>Mylist</name> </filter> </disable-list> </maillist> </packet>

Disabling multiple mailing lists This packet disables mailing lists on Mydomain.com domain.
<packet version="1.4.2.0"> <maillist> <disable-list> <filter> <domain-name>Mydomain.com</domain-name> </filter> </disable-list> </maillist> </packet>

This packet disables mailing lists on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <disable-list> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </enable-list> <enable-list> <filter> <domain-id>6</domain-id> </filter> </disable-list> </maillist> </packet>

Supported Operations

781

Response Packet Structure


The disable-list node of the output XML packet is presented by type MaillistEnableListOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the disable-list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the disable-list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the disable-list operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. This node does not contain any data for this operation. Data type: integer.

782

Supported Operations

Response Samples
Disabling a single mailing list This request packet disables mailing list Mylist.
<packet version="1.4.2.0"> <maillist> <disable-list> <filter> <name>Mylist</name> </filter> </disable-list> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <disable-list> <result> <status>ok</status> <filter-id>Mylist</filter-id> </result> </disable-list> </maillist> </packet>

If the mailing list was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <disable-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Mailing list does not exist</errtext> <filter-id>Mylist</filter-id> </result> </disable-list> </maillist> </packet>

Disabling multiple mailing lists This request packet disables mailing lists on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <disable-list> <filter> <domain-name>Mydomain.com</domain-name>

Supported Operations <domain-name>My2domain.com</domain-name> </filter> </disable-list> <disable-list> <filter> <domain-id>6</domain-id> </filter> </disable-list> </maillist> </packet>

783

If My2domain.com domain was not found, Mydomain.com domain contains two mailing lists, the domain with ID 6 contains one mailing list, the response looks as follows:
<packet version="1.4.2.0"> <maillist> <disable-list> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> </result> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>My2domain.com</filter-id> </result> </disable-list> <disable-list> <result> <status>ok</status> <filter-id>6</filter-id> </result> </disable-list> </maillist> </packet>

Retrieving Status of Mailing Lists Service


Use the get-status operation to retrieve status of mailing list service on a specified domain.

In this section:
Request Packet Structure.................................................................................. 784 Request Samples .............................................................................................. 785 Response Packet Structure ............................................................................... 786 Response Samples ........................................................................................... 787

784

Supported Operations

Request Packet Structure


A request XML packet retrieving status of a mailing lists service includes the get-status operation node:
<packet version="1.4.2.0"> <maillist> <get-status> ... </get-status> </maillist> </packet>

The get-status node is presented by the MaillistGetStatusInputType type (maillist.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on this filter, refer to the Filtering Issues (see page 730) section. Data type: MaillistToggleFilterType (maillist.xsd).

Remarks You can retrieve status of mailing lists service on multiple domains using different filtering rules in a single packet. Add as many get-status operations as the number of different filtering rules to be applied.
<get-status> </get-status> <get-status> </get-status>

Supported Operations

785

Request Samples
Retrieving status of mailing lists service on a single domain This packet retrieves status of the mailing lists service on the domain called Mydomain.com.
<packet version="1.4.2.0"> <maillist> <get-status> <filter> <domain-name>Mydomain.com</domain-name> </filter> </get-status> </maillist> </packet>

Retrieving status of mailing lists service on multiple domains This packet retrieves status of mailing lists service on Mydomain.com and My2domain.com domains.
<packet version="1.4.2.0"> <maillist> <get-status> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </get-status> </maillist> </packet>

This packet retrieves status of mailing lists service on Mydomain.com and My2domain.com domains, and on the domain specified by ID 6.
<packet version="1.4.2.0"> <maillist> <get-status> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </get-status> <get-status> <filter> <domain-id>6</domain-id> </filter> </get-status> </maillist> </packet>

786

Supported Operations

Response Packet Structure


The get-status node of the output XML packet is presented by type MaillistGetStatusOutputType (maillist.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-status operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-status operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-statuse operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 732) section. Data type: anySimpleType. The id node is optional. This node does not contain any data for this operation. Data type: integer. The service-status node is optional. It specifies if the mailing lists service is activated or deactivated. Data type: boolean.

Supported Operations

787

Response Samples
Retrieving status of mailing lists service on a single domain This request packet retrieves status of the mailing lists service on the domain called Mydomain.com.
<packet version="1.4.2.0"> <maillist> <get-status> <filter> <domain-name>Mydomain.com</domain-name> </filter> </get-status> </maillist> </packet>

If the domain contains two mailing lists, a positive response from the server can look as follows:
<packet version="1.4.2.0"> <maillist> <get-status> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <service-status>true</service-status> </result> </get-status> </maillist> </packet>

If the domain was not found on the server, the result looks as follows:
<packet version="1.4.2.0"> <maillist> <get-status> <result> <status>error</status> <status>1015</status> <status>Domain does not exist</status> <filter-id>Mydomain.com</filter-id> </result> </get-status> </maillist> </packet>

Retrieving status of mailing lists service on multiple domains This request packet retrieves status of mailing list service on the domains Mydomain.com, My2domain.com, and on the domain specified by ID 5.
<packet version="1.4.2.0"> <maillist>

788

Supported Operations <get-status> <filter> <domain-name>Mydomain.com</domain-name> <domain-name>My2domain.com</domain-name> </filter> </get-status> <get-status> <filter> <domain-id>5</domain-id> </filter> </get-status> </maillist> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <maillist> <get-status> <result> <status>ok</status> <filter-id>Mydomain.com</filter-id> <service-status>false</service-status> </result> <result> <status>ok</status> <filter-id>My2domain.com</filter-id> <service-status>true</service-status> </result> </get-status> <get-status> <result> <status>ok</status> <filter-id>5</filter-id> <service-status>true</service-status> </result> </get-status> </maillist> </packet>

Supported Operations

789

Managing Plesk Backups


Operator: <backup-manager> XML Schema: backup.xsd Plesk version: 9.0 API RPC version: 1.6.0.0 Plesk user: Plesk Administrator, Plesk reseller, Plesk client Description Important: This operator has no backward compatibility. The current version of the operator described in this section requires Plesk 9 and API RPC 1.6.0.0 (or later versions). To see the description of the earlier operator version compatible with Plesk 8.4 - 8.6, refer to http://download1.parallels.com/Plesk/Plesk8.6/Doc/en-US/plesk-8.6api-rpc/index.htm Backup is a file containing a copy of data that is used to restore the original. In Plesk API RPC, you can manage backups of Plesk accounts or entire Plesk server by the backup-manager operator. One backup may be divided into two or more files. You can use Plesk repository (local storage) or remote FTP servers to store backup files. Protocols other than FTP are not supported in the current realization. Backups are divided into four groups: Domain-level backup. It includes the following: Domain-related content Domain account configuration (limits and permissions on resources, domain administrator personal data, etc.) Domain-level backups of all domains owned by a client Client-level configuration which includes configuration of the client account its subordinary domain accounts Client-level backups of all clients owned by a reseller Reseller-level configuration which includes configuration of the reseller account and client-level configurations of all its subordinary client accounts

Client-level backup. It includes the following:

Reseller-level backup. It includes the following:

Server-level backup. It includes content of all domain accounts on the server and server-level configuration - configuration of Plesk server and all user accounts.

790

Supported Operations

To back up Plesk data, you need to create an instance of the process called backup task with appropriate arguments defining what will be included into backup. If a backup task is successfully completed, the corresponding backup is created. You can monitor the status of backup tasks or cancel them. Supported operations

GET-REMOTE-STORAGE-SETTINGS (on page 792) retrieves settings of a remote FTP storage SET-REMOTE-STORAGE-SETTINGS (on page 796) changes settings of a remote FTP storage BACKUP-DOMAIN (on page 800) creates a domain-level backup task BACKUP-CLIENT (on page 805) creates a client-level backup task BACKUP-RESELLER (on page 809) creates a reseller-level backup task BACKUP-SERVER (on page 813) creates a server-level backup task GET-TASKS-INFO (on page 816) retrieves the status of a certain backup task GET-LOCAL-BACKUP-LIST (on page 822) retrieves a list of backups stored in a local repository IMPORT-FILE (on page 827) moves backups from a temporary directory on Plesk server to a local repository DOWNLOAD-FILE (on page 831) downloads a backup from the server GET-SUPPORTED-PROTOCOLS (on page 833) retrieves transport protocols supported by the backup-manager operator

Supported Operations

791

STOP-BACKUP (on page 835) cancels a certain backup task REMOVE-FILE (on page 839) removes a specified backup from a repository

In this section:
Remote Storage Settings .................................................................................. 791 Retrieving Remote Storage Settings ................................................................. 792 Changing Remote Storage Settings .................................................................. 796 Creating Domain-level Backup Task ................................................................. 800 Creating Client-level Backup Task..................................................................... 805 Creating Reseller-level Backup Task ................................................................. 809 Creating Server-level Backup Task ................................................................... 813 Retrieving Backup Task Status ......................................................................... 816 Retrieving List of Local Backups........................................................................ 822 Adding Backup to Repository ............................................................................ 827 Downloading Backup......................................................................................... 831 Retrieving Protocols Supported by Backup Manager......................................... 833 Cancelling Backup Tasks .................................................................................. 835 Removing Backup ............................................................................................. 839

Remote Storage Settings


To store backups on remote servers, Plesk users should specify settings of a remote storage. The settings include communication protocol between Plesk and the storage, storage host, port or other parameters. Remote storage settings are presented by the settings node. Data type: BackupRemoteStorage (backup.xsd). It has the following graphical representation:

The protocol node is required. It specifies the protocol name. Data type: string. The host node is optional. It specifies the hostname of a storage. Data type: string.

792

Supported Operations

The port node is optional. It specifies the port of the storage. Data type: integer. The directory node is optional. It specifies the directory that stores backups. Data type: string. The login node is optional. It specifies the login to the storage. Data type: string. The password node is optional. It specifies the password to the storage. Data type:string. The passive-mode node is optional. It specifies whether to use passive FTP mode. Data type: boolean. Default value: false.

Note: The nodes except for the protocol stay blank until user specifies the settings.

Retrieving Remote Storage Settings


Use the get-remote-storage-settings operation to retrieve settings of a remote backups FTP storage.

In this section:
Request Packet Structure.................................................................................. 792 Request Samples .............................................................................................. 793 Response Packet Structure ............................................................................... 794 Response Samples ........................................................................................... 795

Request Packet Structure


A request XML packet retrieving remote storage settings includes the get-remote-storagesettings operation node:
<packet version="1.6.0.0"> <backup-manager> <get-remote-storage-settings> ... </get-remote-storage-settings> </backup-manager> </packet>

Supported Operations

793

The get-remote-storage-settings node is presented by type BackupGetRemoteStorageSettingsInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is optional. It specifies the domain ID. Data type: integer. The domain-name node is optional. It specifies the domain name. Data type: string. The client-id node is optional. It specifies the client ID. Data type: integer. The client-login node is optional. It specifies the client login. Data type: string. The reseller-id node is optional. It specifies the reseller ID. Data type: integer. The reseller-login node is optional. It specifies the reseller login. Data type: string. The server node is optional. It instructs Plesk to create a server-level backup. Data type: none. The protocol node is required. It specifies the protocol for which the settings are retrieved. Data type: string. Allowed values: ftp.

Note: If you do not define a target Plesk user, the operation will use packet sender identifier.

794

Supported Operations

Request Samples
This request packet retrieves remote storage settings for the client account with ID 17.
<packet version="1.6.0.0"> <backup-manager> <get-remote-storage-settings> <client-id>17</client-id> <protocol>ftp</protocol> </get-remote-storage-settings> </backup-manager> </packet>

This request packet retrieves remote storage settings for the domain account with ID 7.
<packet version="1.6.0.0"> <backup-manager> <get-remote-storage-settings> <domain-id>7</domain-id> <protocol>ftp</protocol> </get-remote-storage-settings> </backup-manager> </packet>

Response Packet Structure


The get-remote-storage-settings node of the output XML packet is presented by type BackupGetRemoteStorageSettingsOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

Supported Operations

795

The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The settings node is optional. It specifies settings of a remote storage if the operation succeeds. Data type: BackupRemoteStorage (backup.xsd). For details on the node, refer to the Remote Storage Settings (on page 791) section.

Response Samples
This request packet retrieves remote storage settings for the client account with ID 17.
<packet version="1.6.0.0"> <backup-manager> <get-remote-storage-settings> <client-id>17</client-id> <protocol>ftp</protocol> </get-remote-storage-settings> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <get-remote-storage-settings> <result> <status>ok</status> <settings> <protocol>ftp</protocol> <host>ftp.example.com</host> <port>113</port> <directory>/backups/</protocol> <login>myftplogin</login> <password>myftppassword</password> <passive-mode>myftppassword</passive-mode> </settings> </result> </get-remote-storage-settings> </backup-manager> </packet>

796

Supported Operations

If the settings haven't been specified, the response from the server is as follows:
<packet version="1.6.0.0"> <backup-manager> <get-remote-storage-settings> <result> <status>ok</status> <settings> <protocol>ftp</protocol> <host>false</host> <port>21</port> <directory>false</directory> <login>false</login> <password>false</password> <passive-mode>false</passive-mode> </settings> </result> </get-remote-storage-settings> </backup-manager> </packet>

A negative response from the server can look as follows:


<packet version="1.5.1.0"> <backup-manager> <get-remote-storage-settings> <result> <status>error</status> <errcode>1013</errcode> <errtext>client does not exist</errtext> </result> </get-remote-storage-settings> </backup-manager> </packet>

Supported Operations

797

Changing Remote Storage Settings


Use the set-remote-storage-settings operation to change settings of a remote backups FTP storage.

In this section:
Request Packet Structure.................................................................................. 797 Request Samples .............................................................................................. 798 Response Packet Structure ............................................................................... 799 Response Samples ........................................................................................... 799

Request Packet Structure


A request XML packet changing remote storage settings includes the set-remote-storagesettings operation node:
<packet version="1.6.0.0"> <backup-manager> <set-remote-storage-settings> ... </set-remote-storage-settings> </backup-manager> </packet>

The set-remote-storage-settings node is presented by type BackupSetRemoteStorageInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is optional. It specifies the domain ID. Data type: integer. The domain-name node is optional. It specifies the domain name. Data type: string.

798

Supported Operations

The client-id node is optional. It specifies the client ID. Data type: integer. The client-login node is optional. It specifies the client login. Data type: string. The reseller-id node is optional. It specifies the reseller ID. Data type: integer. The reseller-login node is optional. It specifies the reseller login. Data type: string. The server node is optional.. It instructs Plesk to create a server-level backup. Data type: none. The settings node is required. It contains settings of a remote storage. Data type: BackupRemoteStorage (backup.xsd). For details on the node, refer to the Remote Storage Settings (on page 791) section.

Note: If you do not define a target Plesk user, the operation will use packet sender identifier.

Request Samples
This request packet changes remote storage settings for the client account with ID 17.
<packet version="1.6.0.0"> <backup-manager> <set-remote-storage-settings> <client-id>17</client-id> <settings> <protocol>ftp</protocol> <host>ftp.example.com</host> <port>112</port> </settings> </set-remote-storage-settings> </backup-manager> </packet>

This request packet retrieves remote storage settings for domain account with ID 7.
<packet version="1.6.0.0"> <backup-manager> <set-remote-storage-settings> <domain-id>7</domain-id> <settings> <protocol>ftp</protocol> <host>ftp.example.com</host> <port>112</port> </settings> </set-remote-storage-settings> </backup-manager> </packet>

Supported Operations

799

Response Packet Structure


The set-remote-storage-settings node of the output XML packet is presented by type BackupSetRemoteStorageSettingsOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Response Samples
This request packet changes remote storage settings for the client account with ID 17.
<packet version="1.6.0.0"> <backup-manager> <set-remote-storage-settings> <client-id>17</client-id> <settings> <protocol>ftp</protocol> <host>ftp.example.com</host> <port>112</port> </settings> </set-remote-storage-settings> </backup-manager> </packet>

800

Supported Operations

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <set-remote-storage-settings> <result> <status>ok</status> </result> </set-remote-storage-settings> </backup-manager> </packet>

If the client account was not found on the server, the response looks as follows:
<packet version="1.6.0.0"> <backup-manager> <set-remote-storage-settings> <result> <status>error</status> <errcode>1013</errcode> <errtext>client does not exist</errtext> </result> </set-remote-storage-settings> </backup-manager> </packet>

Creating Domain-level Backup Task


Use the backup-domain operation to create a domain-level backup task.

In this section:
Request Packet Structure.................................................................................. 801 Request Samples .............................................................................................. 802 Response Packet Structure ............................................................................... 803 Response Samples ........................................................................................... 804

Supported Operations

801

Request Packet Structure


A request XML packet creating a domain-level backup task includes the backup-domain operation node:
<packet version="1.5.1.0"> <backup-manager> <backup-domain> ... </backup-domain> </backup-manager> </packet>

The backup-domain node is presented by type BackupDomainInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain ID. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string. The local node is required. It specifies if the backup will be stored in the local repository. Data type: none. The remote node is required. It specifies if the backup will be stored in a remote storage. Data type: none. The prefix node is optional. It specifies the backup name prefix. Data type: string. The description node is required. It specifies the description of the backup. Data type: string.

802

Supported Operations

The split-size node is optional. The parameter specifies size of fragments (in Kb) into which the backup is partitioned. Data type: integer. The only-hosting node is optional. The parameter instructs Plesk to exclude mail accounts content from the domain content added to the backup. Data type: none. The only-mail node is optional. The parameter instructs Plesk to add only mail accounts content to the backup. Data type: none. The only-configuration node is optional. The parameter instructs Plesk to include only domain configuration into the backup. Data type: none.

Note: If you do not want to split backup into several files, the split-size value must be set to 0.

Request Samples
The following request packet creates a backup task for the domain account with ID 3:
<packet version="1.6.0.0"> <backup-manager> <backup-domain> <domain-id>3</domain-id> <local/> <prefix>example-domain</prefix> <description>Standard weekly backup</description> <split-size>0</split-size> </backup-domain> </backup-manager> </packet>

The following request packet creates a backup task which instructs Plesk to back up mail accounts on example.com.
<packet version="1.6.0.0"> <backup-manager> <backup-domain> <domain-name>example.com</domain-name> <remote/> <description>Mail accounts backup</description> <only-mail/> </backup-domain> </backup-manager> </packet>

Supported Operations

803

Response Packet Structure


The backup-domain node of the output XML packet is presented by type BackupCommandOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The task-id node is optional. It returns the backup task ID if the operation succeeds. Data type: integer.

804

Supported Operations

Response Samples
The following request packet creates a backup task which instructs Plesk to back up mail accounts on example.com.
<packet version="1.6.0.0"> <backup-manager> <backup-domain> <domain-name>example.com</domain-name> <remote/> <description>Mail accounts backup</description> <only-mail/> </backup-domain> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <backup-domain> <result> <status>ok</status> <task-id>17</task-id> </result> </backup-domain> </backup-manager> </packet>

If the domain account was not found on the server, the response looks as follows:
<packet version="1.6.0.0"> <backup-manager> <backup-domain> <result> <status>error</status> <errcode>1013</errcode> <errtext>Domain does not exist.</errtext> </result> </backup-domain> </backup-manager> </packet>

Supported Operations

805

Creating Client-level Backup Task


Use the backup-client operation to create a client-level backup task.

In this section:
Request Packet Structure.................................................................................. 805 Request Samples .............................................................................................. 806 Response Packet Structure ............................................................................... 807 Response Samples ........................................................................................... 808

Request Packet Structure


A request XML packet creating a client-level backup task includes the backup-client operation node:
<packet version="1.6.0.0"> <backup-manager> <backup-client> ... </backup-client> </backup-manager> </packet>

The backup-client node is presented by type BackupClientInput (backup.xsd), and its graphical representation is as follows:

806

Supported Operations

The client-id node is required. It specifies the client ID. Data type: integer. The client-login node is required. It specifies the client login. Data type: string. The local node is required. It specifies if the backup will be stored in the local repository. Data type: none. The remote node is required. It specifies if the backup will be stored in a remote storage. Data type: none. The prefix node is optional. It specifies the backup name prefix. Data type: string. The description node is required. It specifies the description of the backup. Data type: string. The split-size node is optional. The parameter specifies size of fragments (in Kb) into which the backup is partitioned. Data type: integer. The only-hosting node is optional. The parameter instructs Plesk to exclude mail accounts content from the domains content added to the backup. Data type: none. The only-mail node is optional. The parameter instructs Plesk to add only mail accounts content to the backup. Data type: none. The only-configuration node is optional. The parameter instructs Plesk to include only client-level configuration into the backup. Data type: none.

Note: If you do not want to split backup into several files, the split-size value should be set to 0.

Request Samples
The following request packet creates a backup task which instructs Plesk to perform a client-level backup (without splitting) of the client account with ID 18.
<packet version="1.6.0.0"> <backup-manager> <backup-client> <client-id>18</client-id> <local/> <description>Standard weekly backup</description> <split-size>0</split-size> </backup-client> </backup-manager> </packet>

The following request packet creates a backup task which instructs Plesk to back up client-level configuration of client account with ID 18.
<packet version="1.6.0.0"> <backup-manager> <backup-client> <client-id>18</client-id> <local/> <description>Standard weekly backup</description> <split-size>0</split-size> <only-configuration/> </backup-client> </backup-manager> </packet>

Supported Operations

807

Response Packet Structure


The backup-client node of the output XML packet is presented by type BackupCommandOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The task-id node is optional. It returns the backup task ID if the operation succeeds. Data type: integer.

808

Supported Operations

Response Samples
The following request packet creates a backup task which instructs Plesk to perform a client-level backup (without splitting) of the client account with ID 18.
<packet version="1.6.0.0"> <backup-manager> <backup-client> <client-id>18</client-id> <local/> <description>Standard weekly backup</description> <split-size>0</split-size> </backup-client> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <backup-client> <result> <status>ok</status> <task-id>2</task-id> </result> </backup-client> </backup-manager> </packet>

If the client account was not found on the server, the response looks as follows:
<packet version="1.6.0.0"> <backup-manager> <backup-client> <result> <status>error</status> <errcode>1013</errcode> <errtext>client does not exist.</errtext> </result> </backup-client> </backup-manager> </packet>

Supported Operations

809

Creating Reseller-level Backup Task


Use the backup-reseller operation to create a reseller-level backup task.

In this section:
Request Packet Structure.................................................................................. 809 Request Samples .............................................................................................. 810 Response Packet Structure ............................................................................... 811 Response Samples ........................................................................................... 812

Request Packet Structure


A request XML packet creating a reseller-level backup task includes the backup-reseller operation node:
<packet version="1.6.0.0"> <backup-manager> <backup-reseller> ... </backup-reseller> </backup-manager> </packet>

The backup-reseller node is presented by type BackupResellerInput (backup.xsd), and its graphical representation is as follows:

810

Supported Operations

The reseller-id node is required. It specifies the reseller ID. Data type: integer. The reseller-login node is required. It specifies the reseller login. Data type: string. The local node is required. It specifies if the backup will be stored in the local repository. Data type: none. The remote node is required. It specifies if the backup will be stored in a remote storage. Data type: none. The prefix node is optional. It specifies the backup name prefix. Data type: string. The description node is required. It specifies the description of the backup. Data type: string. The split-size node is optional. The parameter specifies size of fragments (in Kb) into which the backup is partitioned. Data type: integer. The only-hosting node is optional. The parameter instructs Plesk to exclude mail accounts content from the domains content added to the backup. Data type: none. The only-mail node is optional. The parameter instructs Plesk to add only mail accounts content to the backup. Data type: none. The only-configuration node is optional. The parameter instructs Plesk to include only reseller-level configuration into the backup. Data type: none.

Note: If you do not want to split backup into several files, the split-size value should be set to 0.

Request Samples
The following request packet creates a backup task which instructs Plesk to perform a reseller-level backup (without splitting) of the reseller account with ID 18.
<packet version="1.6.0.0"> <backup-manager> <backup-reseller> <client-id>18</client-id> <local/> <description>Standard weekly backup</description> <split-size>0</split-size> </backup-reseller> </backup-manager> </packet>

The following request packet creates a backup task which instructs Plesk to back up configuration of reseller account with ID 18.
<packet version="1.6.0.0"> <backup-manager> <backup-reseller> <reseller-id>18</reseller-id> <local/> <description>Standard weekly backup</description> <split-size>0</split-size> <only-configuration/> </backup-reseller> </backup-manager> </packet>

Supported Operations

811

Response Packet Structure


The backup-reseller node of the output XML packet is presented by type BackupCommandOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The task-id node is optional. It returns the backup task ID if the operation succeeds. Data type: integer.

812

Supported Operations

Response Samples
The following request packet creates a reseller-level backup task for the reseller account with ID 3.
<packet version="1.6.0.0"> <backup-manager> <backup-reseller> <reseller-id>3</reseller-id> <local/> <description>Standard weekly backup</description> </backup-reseller> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <backup-reseller> <result> <status>ok</status> <task-id>2</task-id> </result> </backup-reseller> </backup-manager> </packet>

If the reseller account was not found on the server, the response looks as follows:
<packet version="1.6.0.0"> <backup-manager> <backup-reseller> <result> <status>error</status> <errcode>1013</errcode> <errtext>reseller does not exist.</errtext> </result> </backup-reseller> </backup-manager> </packet>

Supported Operations

813

Creating Server-level Backup Task


Use the backup-server operation to create a server-level backup task.

In this section:
Request Packet Structure.................................................................................. 813 Request Samples .............................................................................................. 814 Response Packet Structure ............................................................................... 815 Response Samples ........................................................................................... 816

Request Packet Structure


A request XML packet creating a server-level backup task includes the backup-server operation node:
<packet version="1.6.0.0"> <backup-manager> <backup-server> ... </backup-server> </backup-manager> </packet>

The backup-server node is presented by type BackupServerInput (backup.xsd), and its graphical representation is as follows:

814

Supported Operations

The local node is required. It specifies if the backup will be stored in the local repository. Data type: none. The remote node is required. It specifies if the backup will be stored in a remote storage. Data type: none. The prefix node is optional. It specifies the backup name prefix. Data type: string. The description node is required. It specifies the description of the backup. Data type: string. The split-size node is optional. The parameter specifies size of fragments (in Kb) into which the backup is partitioned. Data type: integer. The only-hosting node is optional. The parameter instructs Plesk to exclude mail accounts content from the domains content added to the backup. Data type: none. The only-mail node is optional. The parameter instructs Plesk to add only mail accounts content to the backup. Data type: none. The only-configuration node is optional. The parameter instructs Plesk to include only server-level configuration. Data type: none.

Note: If you do not want to split backup into several files, the split-size value should be set to 0.

Request Samples
The following request packet creates a server-level backup task.
<packet version="1.6.0.0"> <backup-manager> <backup-server> <local/> <description>Standard weekly backup</description> </backup-server> </backup-manager> </packet>

The following request packet creates a backup task which instructs Plesk to back up all mail accounts on the server.
<packet version="1.6.0.0"> <backup-manager> <backup-reseller> <local/> <description>Standard weekly backup</description> <only-mail/> </backup-reseller> </backup-manager> </packet>

Supported Operations

815

Response Packet Structure


The backup-server node of the output XML packet is presented by type BackupCommandOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The task-id node is optional. It returns the backup task ID if the operation succeeds. Data type: integer.

816

Supported Operations

Response Samples
The following request packet creates a server-level backup task.
<packet version="1.6.0.0"> <backup-manager> <backup-server> <local/> <description>Standard weekly backup</description> </backup-server> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <backup-server> <result> <status>ok</status> <task-id>2</task-id> </result> </backup-server> </backup-manager> </packet>

Supported Operations

817

Retrieving Backup Task Status


Use the get-tasks-info operation to retrieve the status of backup tasks.

In this section:
Request Packet Structure.................................................................................. 817 Request Samples .............................................................................................. 818 Response Packet Structure ............................................................................... 819 Response Samples ........................................................................................... 821

Request Packet Structure


A request XML packet retrieving the status of backup tasks includes the get-tasks-info operation node:
<packet version="1.6.0.0"> <backup-manager> <get-tasks-info> ... </get-tasks-info> </backup-manager> </packet>

The get-tasks-info node is presented by type BackupGetBackupStatusInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is optional. It specifies the domain ID. Data type: integer. The domain-name node is optional. It specifies the domain name. Data type: string. The client-id node is optional. It specifies the client ID. Data type: integer. The client-login node is optional. It specifies the client login. Data type: string.

818

Supported Operations

The reseller-id node is optional. It specifies the reseller ID. Data type: integer. The reseller-login node is optional. It specifies the reseller login. Data type: string. The server node is optional. It instructs Plesk to display server-level backup tasks. Data type: none. The task-id node is optional. It specifies the task ID. Data type: integer.

Note: If you do not define a target Plesk user, the packet sender identifier will be used in the operation.

Request Samples
The following request packet retrieves the status of the backup tasks for client account MyAccount:
<packet version="1.6.0.0"> <backup-manager> <get-tasks-info> <client-login>MyAccount</client-login> </get-tasks-info> </backup-manager> </packet>

The following request packet retrieves the status of the backup task with ID 7:
<packet version="1.6.0.0"> <backup-manager> <get-tasks-info> <task-id>7</task-id> </get-tasks-info> </backup-manager> </packet>

Supported Operations

819

Response Packet Structure


The get-tasks-info node of the output XML packet is presented by type BackupGetBackupStatusOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

820

Supported Operations

The task node contains details of a backup task. It has the following graphical presentation:

The client-id node is required. It specifies the client ID. Data type: integer. The domain-id node is required. It specifies the domain ID. Data type: integer. The reseller-id node is required. It specifies the reseller ID. Data type: integer. The server node is required. It instructs Plesk to create a server-level backup. Data type: none. The id node is required. It specifies the task ID. Data type: integer. The status node is required. It specifies the execution status of the backup task. Data type: string. Allowed values: working | stopped | failed | finished. The started node is required. It specifies timestamp when the backup task was started. Data type: string. The prefix node is required. It specifies the backup name prefix. Data type: string. The filename node is required. It specifies the full name of the backup. Data type: string. The protocol node is optional. It specifies the used protocol. Data type: string. Allowed values: ftp | local.

Supported Operations

821

Response Samples
The following request packet retrieves the status of backup tasks for the client account with ID 7:
<packet version="1.6.0.0"> <backup-manager> <get-backup-status> <domain-id>7</domain-id> </get-backup-status> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <get-tasks-info> <result> <status>ok</status> <task> <client-id>7</client-id> <id>5472</id> <status>working</status> <started>1224897686</started> <prefix/> <filename/> <protocol>local</protocol> </task> </result> </get-tasks-info> </backup-manager> </packet>

If the client account does not exist, the response looks as follows:
<packet version="1.6.0.0"> <backup-manager> <get-backup-status> <result> <status>error</status> <errcode>1013</errcode> <errtext>Client does not exist.</errtext> </result> </get-backup-status> </backup-manager> </packet>

822

Supported Operations

Retrieving List of Local Backups


Use the get-local-backup-list to retrieve the list of backups stored in the local repository.

In this section:
Request Packet Structure.................................................................................. 822 Request Samples .............................................................................................. 823 Response Packet Structure ............................................................................... 824 Response Samples ........................................................................................... 825

Request Packet Structure


A request XML packet retrieving a list of backups stored in the local repository includes the get-local-backup-list operation node:
<packet version="1.6.0.0"> <backup-manager> <get-local-backup-list> ... </get-local-backup-list> </backup-manager> </packet>

The get-local-backup-list node is presented by type BackupGetLocalBackupListInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain ID. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string. The client-id node is required. It specifies the client ID. Data type: integer. The client-login node is required. It specifies the client login. Data type: string. The reseller-id node is required. It specifies the client ID. Data type: integer.

Supported Operations

823

The reseller-login node is required. It specifies the client login. Data type: string. The server node is required. It instructs Plesk to display server-level backups. Data type: string.

Note: You must specify one of the mentioned nodes in a request packet.

Request Samples
The following request packet retrieves a list of local backups for client account MyAccount:
<packet version="1.6.0.0"> <backup-manager> <get-local-backup-list> <client-login>MyAccount</client-login> </get-local-backup-list> </backup-manager> </packet>

The following request packet retrieves a list of local backups for the domain account with ID 7:
<packet version="1.6.0.0"> <backup-manager> <get-local-backup-list> <domain-id>7</domain-id> </get-local-backup-list> </backup-manager> </packet>

824

Supported Operations

Response Packet Structure


The get-backup-status node of the output XML packet is presented by type BackupGetLocalBackupListOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Supported Operations

825

The backup node is optional. If the operation succeeds, it contains the list of backups stored in the local repository of the specified user. Data type: BackupType (backup.xsd). It can be graphically represented in the following way:

The file node is required. It contains backup details. Data type: BackupFile (backup.xsd). The name node is required. It holds the name of a file included in the backup. Data type: string. The creation-date node is required. It holds the creation date of the file included in the backup. Data type: timestamp. The description node is required. It holds the description of the file included in the backup. Data type: string. The size node is required. It holds the size of the file included in the backup. Data type: size (common.xsd). The not-backup node is optional. It is present in a response packet in case of backup failure. Data type: none.

826

Supported Operations

Response Samples
The following request packet retrieves the list of local backups for client account MyAccount:
<packet version="1.5.1.0"> <backup-manager> <get-local-backup-list> <client-login>MyAccount</client-login> </get-local-backup-list> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.5.1.0"> <backup-manager> <get-local-backup-list> <result> <status>ok</status> <backup> <file> <name>12-11-2003-myclient_3_8.bak</name> <creation-date>1179482633</creation-date> <description/> <size>0</size> <not-backup/> </file> </backup> <backup> <file> <name>priest_2007.05.18_17.12</name> <creation-date>1179483198</creation-date> <description>sdf backup. Creation date: May 18, 2007 05:12 PM</description> <size>128732</size> </file> </backup> </result> </get-local-backup-list> </backup-manager> </packet>

If the account was not found on the server, the response looks as follows:
<packet version="1.5.1.0"> <backup-manager> <get-local-backup-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Client does not exist.</errtext> </result> </get-local-backup-list> </backup-manager> </packet>

Supported Operations

827

Adding Backup to Repository


To add a backup to a local repository, perform two following steps: 1 Upload the backup to the temporary directory on the server using the upload operator. For details on the operator, refer to the Uploading Files to Server (see page 1368) section. Add the backup to the local repository using the import-file operator.

In this section:
Request Packet Structure ..................................................................................827 Request Samples ..............................................................................................828 Response Packet Structure ...............................................................................829 Response Samples ............................................................................................830

Request Packet Structure


A request XML packet moving a backup to the local repository includes the import-file operation node:
<packet version="1.6.0.0"> <import-file> <put-backup> ... </put-backup> </import-file> </packet>

The import-file node is presented by type BackupImportFileInput (backup.xsd), and its graphical representation is as follows:

828

Supported Operations

The domain-id node is required. It specifies the domain ID. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string. The client-id node is required. It specifies the client ID. Data type: integer. The client-login node is required. It specifies the client login. Data type: string. The reseller-id node is required. It specifies the reseller ID. Data type: integer. The reseller-login node is required. It specifies the reseller login. Data type: string. The server node is required. It instructs Plesk to display server-level backup tasks. Data type: none.

Note: You must specify one of the mentioned nodes in a request packet. The tmp-filename node is required. It specifies full name of the backup retrieved from the response packet of the upload operation. Data type: string.

Request Samples
Using the upload operator, backup MyBackup.bak was successfully uploaded to the server.
<packet version="1.6.0.0"> <upload> <result> <status>ok</status> <name>MyBackup</name> <file>/usr/local/psa/tmp/MyBackup.bak</file> </result> </upload> </packet>

The request packet moving the backup to the local repository of the client with ID 54 looks as follows:
<packet version="1.6.0.0"> <backup-manager> <put-backup> <client-id>54</client-id> <tmp-filename>/usr/local/psa/tmp/MyBackup.bak</tmp-filename> </put-backup> </backup-manager> </packet>

Supported Operations

829

Response Packet Structure


The import-file node of the output XML packet is presented by type BackupImportFileOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

830

Supported Operations

Response Samples
The request packet moving the backup to the local repository of the client with ID 54 looks as follows:
<packet version="1.6.0.0"> <backup-manager> <put-backup> <client-id>54</client-id> <tmp-filename>/usr/local/psa/tmp/MyBackup.bak</tmp-filename> </put-backup> </backup-manager> </packet>

A positive response from the server can look as follows:


<packet version="1.6.0.0"> <backup-manager> <put-backup> <result> <status>ok</status> </result> </put-backup> </backup-manager> </packet>

If the file was not found on the server, the response looks as follows:
<packet version="1.6.0.0"> <backup-manager> <put-backup> <result> <status>error</status> <errcode>1013</errcode> <errtext>File does not exist.</errtext> </result> </put-backup> </backup-manager> </packet>

Supported Operations

831

Downloading Backup
Use the download-file to download a backup from a local repository. Note: Do not use other operations in the same packet with this operation, because structure of a download-file response packet varies depending on the result of the operation. In case the file has been successfully downloaded, the response contains attached backup file. If any error occurs, the response contains XML packet with the error data.

In this section:
Request Packet Structure.................................................................................. 831 Request Samples .............................................................................................. 832 Response Packet Structure ............................................................................... 832 Response Samples ........................................................................................... 833

Request Packet Structure


A request XML packet downloading a backup from a local repository includes the download-file operation node:
<packet version="1.6.0.0"> <backup-manager> <download-file> ... </download-file> </backup-manager> </packet>

The download-file node is presented by type BackupDownloadFileInput (backup.xsd), and its graphical representation is as follows:

832

Supported Operations

The domain-id node is required. It specifies the domain ID. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string. The client-id node is required. It specifies the client ID. Data type: integer. The client-login node is required. It specifies the client login. Data type: string. The reseller-id node is required. It specifies the client ID. Data type: integer. The reseller-login node is required. It specifies the client login. Data type: string. The server node is required. It instructs Plesk to display server-level backups. Data type: string. Note: You must specify one of the mentioned nodes in a request packet.

The filename node is optional. It specifies the name of the backup in the local repository. Data type: string.

Request Samples
The request packet downloading backup MyBackup.bak from the local repository looks as follows:
<packet version="1.5.1.0"> <backup-manager> <download-file> <filename>MyBackup.bak</filename> </download-file> </backup-manager> </packet>

Response Packet Structure


The download-file node of the output XML packet is presented by type BackupDownloadFileOutput (backup.xsd) and structured as follows:

Supported Operations

833

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Response Samples
The request packet downloading backup MyBackup.bak from a local repository looks as follows:
<packet version="1.6.0.0"> <backup-manager> <download-file> <filename>MyBackup.bak</filename> </download-file> </backup-manager> </packet>

A positive response from the server can look as follows:


Content-Type: application/octet-stream Content-Disposition: attachment; filename=MyBackup.bak Pragma: no-cache <backup data>

If the file does not exist on the server, the response is as follows:
<packet version="1.6.0.0"> <backup-manager> <download-file> <result> <status>error</status> <errcode>1013</errcode> <errtext>The file MyBackup.bak does not exist</errtext> </result> </download-file> </backup-manager>

834

Supported Operations

Retrieving Protocols Supported by Backup Manager


Use the get-supported-protocols to retrieve transport protocols supported by the backupmanager operator.

In this section:
Request Packet ................................................................................................. 834 Response Packet Structure ............................................................................... 834 Response Samples ........................................................................................... 835

Request Packet
A request XML packet retrieving protocols supported by backup-manager includes the get-supported-protocols operation node:
<packet version="1.6.0.0"> <backup-manager> <get-supported-protocols/> </backup-manager> </packet>

The get-supported-protocols node is required. Data type: none.

Response Packet Structure


The get-supported-protocols node of the output XML packet is presented by type BackupGetSupportedProtocolsOutput (backup.xsd) and structured as follows:

Supported Operations

835

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The protocol node is optional. If the operation succeeds, it contains a list of supported protocols. Data type: string.

Response Samples
The request packet looks as follows:
<packet version="1.6.0.0"> <backup-manager> <get-supported-protocols/> </backup-manager> </packet>

A positive response from the server looks as follows:


<packet version="1.6.0.0"> <backup-manager> <get-supported-protocols> <result> <status>ok</status> <protocol>ftp</protocol> </result> </get-supported-protocols> </backup-manager>

836

Supported Operations

Cancelling Backup Tasks


Use the stop-backup to cancel a backup task.

In this section:
Request Packet Structure.................................................................................. 836 Request Samples .............................................................................................. 836 Response Packet Structure ............................................................................... 837 Response Packet Samples ............................................................................... 838

Request Packet Structure


A request XML packet cancelling a includes the stop-backup operation node:
<packet version="1.6.0.0"> <backup-manager> <stop-backup> ... </stop-backup> </backup-manager> </packet>

The stop-backup node is presented by type BackupStopInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the task ID. Data type: integer.

Request Samples
The following packet cancels the backup task with ID 5.
<packet version="1.6.0.0"> <backup-manager> <stop-backup> <task-id>5</task-id> </stop-backup> </backup-manager> </packet>

Supported Operations

837

Response Packet Structure


The stop-backup node of the output XML packet is presented by type BackupStopOutput (backup.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

838

Supported Operations

Response Packet Samples


The following packet cancels the backup task with ID 5.
<packet version="1.6.0.0"> <backup-manager> <stop-backup> <task-id>5</task-id> </stop-backup> </backup-manager> </packet>

A positive response from the server looks as follows:


<packet version="1.6.0.0"> <backup-manager> <stop-backup> <result> <status>ok</status> </result> </stop-backup> </backup-manager> </packet>

If the backup task is not running, the response looks as follows:


<packet version="1.6.0.0"> <backup-manager> <stop-backup> <result> <status>error</status> <errcode>1002</errcode> <errtext>Attempt to get working dir for not running backup</errtext> </result> </stop-backup> </backup-manager> </packet>

Supported Operations

839

Removing Backup
Use the remove-file to remove a backup from the local repository.

In this section:
Request Packet Structure.................................................................................. 839 Request Samples .............................................................................................. 840 Response Packet Structure ............................................................................... 840 Response Samples ........................................................................................... 841

Request Packet Structure


A request XML packet removing a backup from the local repository includes the removefile operation node:
<packet version="1.5.1.0"> <backup-manager> <remove-file> ... </remove-file> </backup-manager> </packet>

The remove-file node is presented by type BackupRemoveFileInput (backup.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain ID. Data type: integer. The domain-name node is required. It specifies the domain name. Data type: string. The client-id node is required. It specifies the client ID. Data type: integer. The client-login node is required. It specifies the client login. Data type: string.

840

Supported Operations

The reseller-id node is required. It specifies the client ID. Data type: integer. The reseller-login node is required. It specifies the client login. Data type: string. The server node is required. It instructs Plesk to display server-level backups. Data type: string. Note: You must specify one of the mentioned nodes in a request packet.

The filename node is required. It specifies the name of the backup in the local repository. Data type: string.

Remarks You can remove backups stored in the local repository of a domain administrator or client. To remove a backup of a client account, Plesk Administrator should specify the client login or ID. To remove a backup of a domain account, Plesk users should specify the domain ID or name.

Request Samples
The request packet removing backup MyBackup.bak from the local repository of the client account with ID 114 looks as follows:
<packet version="1.5.1.0"> <backup-manager> <remove-file> <client-id>114</client-id> <filename>MyBackup.bak</filename> </remove-file> </backup-manager> </packet>

Response Packet Structure


The stop-backup node of the output XML packet is presented by type BackupRemoveFileOutput (backup.xsd) and structured as follows:

Supported Operations

841

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Response Samples
The request packet removing backup MyBackup.bak from the local repository of the client account with ID 114 looks as follows:
<packet version="1.6.0.0"> <backup-manager> <remove-file> <client-id>114</client-id> <filename>MyBackup.bak</filename> </remove-file> </backup-manager> </packet>

A positive response from the server looks as follows:


<packet version="1.6.0.0"> <backup-manager> <remove-file> <result> <status>ok</status> </result> </remove-file> </backup-manager> </packet>

If the file is not found on the server, the response from the server looks as follows:
<packet version="1.6.0.0"> <backup-manager> <remove-file> <result> <status>error</status> <errcode>1013</errcode> <errtext>The file MyBackup.bak does not exist</errtext> </result> </remove-file> </backup-manager> </packet>

842

Supported Operations

Managing Plesk Server


Operator: <server> XML Schema: plesk_server.xsd, server_input.xsd, server_output.xsd Plesk version: all versions API RPC version: all versions Plesk user: Plesk Administrator Description The server operator is designed for performing various operations on logical objects existing on the server level: API RPC protocol Plesk license Plesk Administrator Server services Server statistics

Supported operations

GET_PROTOS (see page 850) gets API RPC protocol versions supported on the server

Supported Operations

843

GET (see page 864) gets various information on server configuration, Plesk Administrator data and settings, license key, general Plesk configuration, Plesk services and statistics

SET (see page 897) changes Administrators password and personal information and settings, and configures server traffic statistics and user's session settings

SRV_MAN (see page 901) starts, stops, and restarts Plesk server services

LIC_INSTALL (see page 861) installs Plesk license key

INITIAL_SETUP (see page 851) configures Plesk server for the first time

GET_ADDITIONAL_KEY (see page 855) retrieves license keys for Plesk add-ons

In this section:
Administrator Personal Information ................................................................... 843 Server Preferences ........................................................................................... 846 Getting Supported Protocols ............................................................................. 850 Performing Initial Server Setup .......................................................................... 851 Managing Plesk License ................................................................................... 855 Getting Server Information ................................................................................ 864 Setting Up Server .............................................................................................. 897 Managing Plesk Services .................................................................................. 901

844

Supported Operations

Administrator Personal Information


Personal information of Plesk server Administrator is held by the admin node presented by complex type adminType (plesk_server.xsd). Together with the personal info, the node specifies if the Parallels announcements should be sent to the Administrator's e-mail. The node is structured as follows:

The admin_cname node is required. It holds the administrator's company name. Data type: string (0 to 60 characters long). The admin_pname node is required. It holds the administrator's personal name. Data type: string (0 to 60 characters long). The admin_phone node is required. It holds the administrator's phone number. Data type: string. The admin_fax node is required. It holds the administrator's fax number. Data type: string. The admin_email node is required. It holds the administrator's e-mail address. Data type: emailType (common.xsd).

Supported Operations

845

The admin_address node is required. It holds the administrator's street address. Data type: string. The admin_city node is required. It holds the name of the city where administrator lives. Data type: string. The admin_state node is required. It holds the name of state (for US citizens) or province where administrator lives. Data type: string. The admin_pcode node is required. It holds the administrator's zip/ postal code. Data type: zipcodeType (common.xsd). The admin_country node is required. It holds the name of the country where administrator lives. Data type: string. Value restrictions: two-letters upper-case country nomination in accordance with ISO 3166 (http://www.iso.org/iso/en/prodsservices/iso3166ma/02iso-3166-code-lists/list-en1.html). The send_announce node is required. It specifies whether Parallels announcement messages are sent to the administrator's e-mail specified in the admin_email node . Data type: boolean. The uid and the global-login nodes are deprecated.

XML request packet changing Administrator's personal information and settings looks as follows:
<packet version="1.4.2.0"> <server> <set> <admin> <admin_cname>JohnDoe BV.</admin_cname> <admin_pname>John Doe</admin_pname> <admin_phone>+49 89333333</admin_phone> <admin_fax>+49 893333303</admin_fax> <admin_email>john@doe.de</admin_email> <admin_address>Theatinerstrasse 96</admin_address> <admin_city>Muenchen</admin_city> <admin_state>Bavaria</admin_state> <admin_pcode>80333</admin_pcode> <admin_country>DE</admin_country> <send_announce>true</send_announce> </admin> </set> </server> </packet>

846

Supported Operations

A response XML packet retrieving Administrator's personal information and settings looks as follows:

<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <admin> <admin_cname>JohnDoe BV.</admin_cname> <admin_pname>John Doe</admin_pname> <admin_phone>+49 89333333</admin_phone> <admin_fax>+49 893333303</admin_fax> <admin_email>john@doe.de</admin_email> <admin_address>Theatinerstrasse 96</admin_address> <admin_city>Muenchen</admin_city> <admin_state>Bavaria</admin_state> <admin_pcode>80333</admin_pcode> <admin_country>DE</admin_country> <send_announce>true</send_announce> </admin> </result> </get> </server> </packet>

Supported Operations

847

Server Preferences
When talking about Plesk server preferences, we mean the following: Apache restart interval (for Plesk for Unix only) the number of seconds after which Apache should be restarted traffic statistics time-to-live the period (in month) during which the server traffic statistics should be stored traffic accounting type if the inbound or/and outbound traffic should be calculated

Plesk server preferences are held by the prefs node. The node is presented by complex type serverPrefs (plesk_server.xsd) and structured as follows:

The stat_ttl node is optional. It specifies the time-to-live of server traffic statistics. Data type: integer. The traffic_accounting node is optional. It specifies the traffic accounting type. Data type: integer. Allowed values: 1 (only inbound) | 2 (only outbound) | 3 (inbound & outbound). The restart_apache_interval node is optional. It specifies Apache restart interval (in seconds). Data type: integer. Supported in Plesk for Unix only. The aps-catalog-url node is optional. It specifies the URL on an APS Catalog. This option is supported since API RPC 1.6.0.0. Data type: string.

848

Supported Operations

XML request packets setting up or changing server preferences may look as follows:
<packet version="1.4.2.0"> <server> <set> <prefs> <stat_ttl>3</stat_ttl> <traffic_accounting>3</traffic_accounting> <restart_apache_interval>0</restart_apache_interval> </prefs> </set> </server> </packet>

This packet is formed for sending to the server running Plesk for Unix. When operation succeeds, both inbound and outbound traffic will be included to server traffic statistics, which will be stored during 3 months. Also, Apache will not be restarted automatically.
<packet version="1.4.2.0"> <server> <set> <prefs> <stat_ttl>5</stat_ttl> <traffic_accounting>2</traffic_accounting> </prefs> </set> </server> </packet>

This packet is formed for sending to the server running Plesk for Windows, only outbound traffic should be calculated, and the traffic statistics should be stored during 5 months.

Supported Operations

849

XML response packet retrieving server preferences may look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <prefs> <stat_ttl>4</stat_ttl> <traffic_accounting>3</traffic_accounting> <restart_apache_interval>86400</restart_apache_interval> </prefs> </result> </get> </server> </packet>

This packet is received from the server running Plesk for Unix where both inbound and outbound traffic are included to server traffic statistics, which is stored during 4 months. Also, Apache is restarted each 24 hours.
<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <prefs> <stat_ttl>6</stat_ttl> <traffic_accounting>2</traffic_accounting> </prefs> </result> </get> </server> </packet>

This packet is received from the server running Plesk for Windows where only outbound traffic is calculated, and the traffic statistics are stored during 6 months.

850

Supported Operations

Getting Supported Protocols


To retrieve a list of API RPC protocol versions supported on a Plesk server, send to the server a request packet with the get_protos operational node:
<packet version="1.4.2.0"> <server> <get_protos/> </server> </packet>

The get_protos node is presented by the GetProtosType (server_input.xsd). Response packet The get_protos node of the response packet received from server is presented by the complex type GetProtosType (server_output.xsd) and is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: GetProtosResultType (server_output.xsd). The status node is required. It specifies the execution status of the get_protos operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the get_protos operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the get_protos operation fails. Data type: string. The protos node is required if the get_protos operation has succeeded. It hold the list of API RPC protocol versions supported on the server. Data Type: ProtosList (server_output.xsd). The proto node is required if the get_protos operation has succeeded. It specifies a supported version of API RPC protocol. Data type: string.

Supported Operations

851

A positive response received from server can look as follows:


<packet version="1.4.2.0"> <server> <get_protos> <result> <status>ok</status> <protos> <proto>1.0.0.0</proto> <proto>1.1.0.0</proto> <proto>1.2.0.0</proto> <proto>1.3.0.0</proto> <proto>1.3.1.0</proto> <proto>1.3.2.0</proto> <proto>1.3.3.0</proto> <proto>1.3.4.0</proto> <proto>1.3.5.0</proto> <proto>1.4.0.0</proto> <proto>1.4.1.0</proto> <proto>1.4.2.0</proto> <proto>1.4.1.1</proto> <proto>1.4.1.2</proto> </protos> </result> </get_protos> </server> </packet>

Performing Initial Server Setup


Initial server setup is performed right after installing Plesk on a server. This operation includes: Specifying Plesk Administrator's personal information Changing default Plesk Administrator's password Specifying full host name

To initially set up Plesk server, use the initial_setup operation. Note: Using the initial_setup operation later on to change administrator's password or personal info is prohibited. For this purposes, use the set (see page 897) operation instead.

In this section:
Request Packet Structure.................................................................................. 852 Request Samples .............................................................................................. 853 Response Packet Structure ............................................................................... 853 Response Samples ........................................................................................... 854

852

Supported Operations

Request Packet Structure


A request XML packet starting server initial setup contains the initial_setup operation node:
<packet version="1.4.2.0"> <server> <initial_setup> ... </initial_setup> </server> </packet>

The initial_setup node is presented by complex type initialSetupType (plesk_server.xsd) and structured as follows:

The admin node is required. It holds the collection of data describing Plesk Administrator's personal info. Data type: adminType (plesk_server.xsd). For information on this node structure, refer to the Administrator Personal Information (see page 843) section. The password node is required. It holds the new Plesk Administrator's password that will replace the default one. Data type: serverPassword (plesk_server.xsd). Allowed values: 5 to 14 characters. The server_name node is optional. It specifies the full host name. Data type: string.

Supported Operations

853

Request Samples
A request packet performing initial setup of Plesk server can look as follows:
<packet version="1.4.2.0"> <server> <initial_setup> <admin> <admin_cname>JohnDoe BV.</admin_cname> <admin_pname>John Doe</admin_pname> <admin_phone>+49 89333333</admin_phone> <admin_fax>+49 893333303</admin_fax> <admin_email>john@doe.de</admin_email> <admin_address>Theatinerstrasse 96</admin_address> <admin_city>Muenchen</admin_city> <admin_state>Bavaria</admin_state> <admin_pcode>80333</admin_pcode> <admin_country>DE</admin_country> <send_announce>true</send_announce> </admin> <password>setup</password> <server_name>com3.doe.de</server_name> </initial_setup> </server> </packet>

Response Packet Structure


The initial_setup node of the response packet is structured as follows:

854

Supported Operations

The result node is required. It wraps the result of the initial_setup operation. Data type: InitialSetupResultType (server_output.xsd). The status node is required. It returns the execution status of the initial_setup operation. Data type: string (common.xsd). Allowed values: ok | error. The errcode node is optional. It returns the error code when the initial_setup operation fails. Data type: unsignedInt (integer). The errtext node is optional. It returns the error message if the initial_setup operation fails. Data type: string. The server_name node is required if the initial_setup operation succeeds. It returns the name of the server on which initial setup was successfully performed. Data type: string.

Response Samples
A positive response received from server looks as follows:
<packet version="1.4.2.0"> <server> <initial_setup> <result> <status>ok</status> <server_name>com3.doe.de</server_name> </result> </initial_setup> </server> </packet>

A negative response received from server may look as follows:


<packet version="1.4.2.0"> <server> <initial_setup> <result> <status>error</status> <errcode>1003</errcode> <errtext>Initial setup already completed</errtext> <server_name>com3.doe.de</server_name> </result> </initial_setup> </server> </packet>

Such error is received if the request packet sent to the server tried to perform initial setup on a server where it has already been done.

Supported Operations

855

Managing Plesk License


Plesk license determines What Plesk functionality is available when using a particular Plesk instance How many Plesk logical objects (Client accounts, Domain accounts, mailboxes, web users, etc.) can be created in a particular Plesk instance

Plesk Administrator has full set of privileges required for managing Plesk license. The following operations are available via Plesk API RPC protocol: Retrieving information on the currently installed Plesk license key Installing new license key Retrieving additional keys (required for Plesk add-ons) installed on the server

In this section:
Retrieving License Key ......................................................................................855 Retrieving Additional License Keys ....................................................................855 Installing License Key ........................................................................................861

Retrieving License Key


To retrieve the Plesk license key currently installed on a server, use the get (see page 864) operation with the key parameter specified. A request XML packet getting license key contains the key node nested within the get operational node:
<packet version="1.4.2.0"> <server> <get> <key/> </get> </server> </packet>

For information on the response packet structure and response samples, refer to the Getting Server Information: License Key (see page 870) section.

856

Supported Operations

Retrieving Additional License Keys


The get_additional_key operation retrieves data of additional key installed on the server, such as the key name and number, key expiration date and usage (whether the key is active or not), key content and other properties.

In this section:
Request Packet Structure.................................................................................. 856 Request Samples .............................................................................................. 857 Response Packet Structure ............................................................................... 858 Response Samples ........................................................................................... 860

Request Packet Structure


A request XML packet retrieving additional key data contains the get_additional_key operation node:
<packet version="1.4.2.0"> <server> <get_additional_key> ... </get_additional_key> </server> </packet>

The get_additional_key node is presented by complex type GetAdditionalKeyType (server_input.xsd) and structured as follows:

The filter node is optional. It wraps the filtering rules defining which additional keys data to retrieve. Data type: GetAdditionalKeysFilter (server_input.xsd). The name node is optional. It specifies the additional key in format "[key_number]/[key_name]". See the Request Samples (see page 857) section for examples. Data type: string.

Supported Operations

857

To retrieve data of all additional keys installed on the server, use empty filter node, or omit it at all and send packet with empty get_additional_key node:
<packet version="1.4.2.0"> <server> <get_additional_key> <filter/> </get_additional_key> </server> </packet>

or
<packet version="1.4.2.0"> <server> <get_additional_key/> </server> </packet>

Request Samples
This packet retrieves data of the additional license key with number PLSK002694000000 and name antivir-drweb-4, which is the license key allowing using such additional Plesk feature as DrWeb Antivirus.
<packet version="1.4.2.0"> <server> <get_additional_key> <filter> <name>PLSK002694000000/antivir-drweb-4</name> </filter> </get_additional_key> </server> </packet>

This packet retrieves data of all additional license keys installed on server:
<packet version="1.4.2.0"> <server> <get_additional_key/> </server> </packet>

858

Supported Operations

Response Packet Structure


The get_additional_key node of the response packet is structured as follows:

The result node is required. It wraps the result of the get_additional_key operation. Data type: GetAdditionalKeyResultType (server_output.xsd). The status node is required. It returns the execution status of the get_additional_key operation. Data type: string (common.xsd). Allowed values: ok | error. The errcode node is optional. It returns the error code when the get_additional_key operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get_additional_key operation fails. Data type: string. The name node is optional. It returns the value of the name node from request packet if retrieving the specified key info is impossible. Data type: string. The key_info node is optional. It is required if the response successfully retrieves data of the specified key. Data type: additionalKeyType (server_output.xsd). The node structure is the following:

Supported Operations

859

The number node is required. It returns the key number. Data type: string. The name node is required. It returns the full key name in format "[key_number]/[key_name]". Data type: string. The active node is required. It specifies if the key is installed and working, or if it is expired. Data type: boolean. The license_update_date node is required if key expiration date is defined. It returns the date (in format YYYYMMDD) when a grace period starts, during which the key must be updated. Data type: integer. The lim_date node is optional. It returns the date (in format YYYYMMDD) when the key expires. Data type: integer. The content node is required. It returns the key body. Data type: base64. The property node is optional. It holds the collection of data describing a particular key property. Data type: AdditionalKeyPropertyType (server_output.xsd). The name node is required. It returns . Data type: string. The value node is required. It returns . Data type: string.

860

Supported Operations

Response Samples
A positive response received from server can look as follows (the key content is greatly reduced):
<packet version="1.4.2.0"> <server> <get_additional_key> <result> <status>ok</status> <key_info> <number>PLSK002694000000</number> <name>PLSK002694000000/antivir-drweb-4</name> <active>true</active> <license_update_date>20060506</license_update_date> <lim_date>20060511</lim_date> <content>IyEvYmluL3NoCgpQUk9EVUNUX1JPT1RfRD1gYXdrICckMSB+IC9QUk9EVUNUX 1JPT1RfRC97IHByaW50ICQyfScgL2V0Yy9wc2EvcHNhLmNvbmZgCmlmIHRlc3QgLXogIiR QUk9EVUNUX1JPT1RfRCI7IHRoZW4KZWNobyAiUGxlc2sgbm90IGRldGVjdGVkIgpleGl0I DEKZmkKIiRQUk9EVUNUX1JPT1RfRC9hZG1pbi9zYmluL2tleW1uZyIgLS1pbnN0YWxsLWF kZGl0aW9uYWwgLS1zb3VyY2UtZmlsZT0iJDAiIC0tc2tpcD01CmV4aXQgJD8KCi0tLS0tQ kVHSU4gUExFU0sgQURESVRJT05BTCBLRVktLS0tLQprZXlfbnVtYmVyPSdQTFNLMDAyNjk 0NzMwMDAwJwprZXk9J095QkVjbGRsWWpNeUlIWTBMakUyS3lCTFpYa2dSbWxzWlEwS095Q kVieUJ1YjNRZ1pXUnBkQ0VOQ2cwS095QWVIeDRmSGg4ZUh4NGZIaDhlSHg0ZkhoOGVIeDR mSGcwS0RRcGJTMlY1WFEwS1ZsSTlNREF3TURBd01EQXdNQTBLUVZBOU1EQXdNRFV5TkRNe U1BMEtRMUk5TVRFME5EY3pPVEl6T1EwS1JWZzlNVEUwTnpNek1USXpPUTBLVTBVOU1URTB Oek16TVRJek9RMEtWbVZ5YzJsdmJqMUJiR3dOQ2tGd2NHeHBZMkYwYVc5dWN6MUVjbGRsW WxWdWFYZ3NUV0ZwYkVSaFpXMXZibFZ1YVhnTkNrTnlaV0YwWldROU1qQXdOaTB3TkMweE1 TQW9NRGM2TURjcElGVlVRdzBLUlhod2FYSmxjejB5TURBMkxUQTFMVEV4SUNnd056b3dOe WtnVlZSRERRcFRkV0p6WTNKcGNIUnBiMjVGZUhCcGNtVnpQVEl3TURZdE1EVXRN</conte nt> <property> <name>name</name> <value>antivir-drweb-4</value> </property> <property> <name>filename</name> <value>/etc/psa/key.d/keyyV1LsN</value> </property> <property> <name>key</name> <value>OyBEcldlYjMyIHY0LjE2KyBLZXkgRmlsZQ0KOyBEbyBub3QgZWRpdCENCg0KOyA eHx4fHh8eHx4fHh8eHx4fHh8eHx4fHg0KDQpbS2V5XQ0KVlI9MDAwMDAwMDAaW9ucz1Ecl dlYlVuaXgsTWFpbERhZW1vblVuaXgNCkNyZWF0ZWQ9MjAwNi0wNC0xMSAoMDc6MDcpIFVU Qw0KRXhwaXJlcz0yMDA2LTA1LTExICgwNzowNykgVVRDDQpTdWJzY3JpcHRpb25FeHBpcm VzPTIwMDYtMDUtMTEgKDA3OjA3KSBVVEMNCg0KW0RlYWxlcl0NCk51bWJlcj0wMDEwMDAw value> </property> </key_info> </result> </get_additional_key> </server> </packet>

Supported Operations

861

If no additional license keys are installed, server returns positive response packet where the key_info node is missing:
<packet version="1.4.2.0"> <server> <get_additional_key> <result> <status>ok</status> </result> </get_additional_key> </server> </packet>

A negative response received from server may look as follows:


<packet version="1.4.2.0"> <server> <get_additional_key> <result> <status>error</status> <errcode>1013</errcode> <errtext>Key is not found</errtext> <name>antivir-drweb-4</name> </result> </get_additional_key> </server> </packet>

This error was received because the request packet tried to retrieve additional key defined not by its full name (see the value of the name node).

Installing License Key


Plesk comes with a trial license key which is automatically installed to the control panel. This license key allows to create 1 Client account, 1 Domain account and 1 mailbox. Therefore, to fully use Plesk as you need, you should obtain a license key from Parallels or one of its resellers and install it to the control panel. Once you have ordered new license key and received it to your e-mail, you can install it to Plesk. For this, use the lic_install operation. This operation is also used for installing additional license keys that allow using Plesk additional features (add-ons) like Acronis True Image, Kaspersky Antivirus, and so on.

In this section:
Request Packet Structure.................................................................................. 862 Request Samples .............................................................................................. 862 Response Packet Structure ............................................................................... 863 Response Samples ........................................................................................... 864

862

Supported Operations

Request Packet Structure


A request XML packet installing license key to Plesk contains the lic_install operation node:
<packet version="1.4.2.0"> <server> <lic_install> ... </lic_install> </server> </packet>

The lic_install node is presented by complex type LicenseInstallType (server_input.xsd) and structured as follows:

The license node is required. It contains the license key data. Data type: base64. The additional_key node is optional. It specifies if the key that will be installed is an additional key. Data type: none.

Request Samples
This packet installs a license key (the key content is greatly reduced).
<packet version="1.4.2.0"> <server> <lic_install> <license>/RjdfLic1RwpNPkEnLlxNJkJCPzNDWSRDOyVeJDI/MSo1RlFEMD4+VTEzKTk3 S0pfVjFOJTZFXzMpTEVPQC5JRjdUR0RZCk0hMSJYOzYhVFxPI14jTFJPRSlaRFI0VjZWPE YiT1s5T0opJV8+NCMnUigvQ1o7K0U+QEtbISc1MlMqLV0KTSorUDVfMzxHNUkrSksxWzZV NVZJXTc5T18xQVNNNzRXWTo3WVkmW0I/J2AnYC4iJTlTP1grSCdYS0E+RApNPVteRk43RC NAVFpVO0dBO1hZMjo+K0pQNEsiLj5UUDQlLDA7XyVZIVo/QypGJiJcW1FbJF1fVVxUJy5E Ck1HXCpSUzwtUVYoJzwsVV47MT5bJD8wWlgyYCo/KTM0QUJFMmAuOjc7QypMWylfQiFVP0 5PRj05LCY5SkgKTVRTWE9cRi84OUgxJDpgLl5RPEtPPkE4RCUtXU06NixHLi1ZL0ZBVSky VkBVUCgiN0YrKyoyXTJMJ08qVwpNIk4lOyFeLFwmIiQ4NkBgMUEmTDRcWDdJKihZTEMhTE NOJTQuLkBFMVk2I0REUCItXyVMNlRPRkEyTEA7Pl9QO10jUSI6I1tNIzVRU0VZVE1HWDIn Izk4Ck1XRUNPVz5CSFUjUSo4K0IvOFlDWSNTLydXSls7KD9VTD8+WzUqQEA5Uic0S1BMJS owOk9fQ0QvQThUVCEKTT1AKiJFKztAKCFXNl9ORDhUVlleOCU5JS8rJzc+JEZUXigzMDs4 PDtbNkUpPD8vUiJAREQoTkxUPlQ2JgpNVFdbVz9bT10mVy5FVEkyXD5MPSIkMkRVVipKWT olXVhRTzkoM1tLLSJRJFlXNTRTYEBNWy1UUV09K04wCk1SVWBbLyckXj5KXjsnUzgyRzE3 QVUlWilXX0ZCX1BGMkRMSThHXjZBWE5FTUBEMjBgRTomVTpVLy1WRCQKTVtWUyQ+XDcsRU A+XU0hXz4pKFxBJ1JCNUQ6XCEnQjoyPFw</license> </lic_install> </server> </packet>

Supported Operations

863

This request packet installs additional license key (the key content is greatly reduced).
<packet version="1.4.2.0"> <server> <lic_install> <license>LS0tLS1CRUdJTiBQTEVTSyBBRERJVElPTkFMIEtFWS0tLS0tCmtleV9udW1iZ XI9J1BMU0swMDA0MTEzNjAwMDEnCmh3aWQ9J25vdC1yZXF1aXJlZCcKa2V5PSc3YzAzZTF lZDhjNjEyMTNhZDZjZmM1NjFmNjc5YTE4MicKbGltX2RhdGU9MApuYW1lPSdzYXBwLVBQV 1NFLTEnCi0tLS0tQkVHSU4gUExFU0sgQURESVRJT05BTCBLRVkgU0lHTkFUVVJFLS0tLS0 KOGM2MGZmZjYxZjUyMWVmYTdlOWZjNDZhNTAzZGJmNDVmZDEyZGZiMWUxY2JlMmYwMGEwZ TVhZmQwMDAzMGE4ZjUyOTk5ZGZmMjNjOGIyZGY2NjRkNTQ2ZWNiYmE1OTFmZGQyNjdkNWI 5OWM1NTgzZTg2N2RkNjNlMmU1ZjMxMzlmOTM3NGNiNTI4MDRhNzE3ZTAzN2Y4MDQzY2QyO DczMDgyMTg1N2QyN2Y2M2VmYjdjNzEzZGE2MDRlYzFlZGRhMWQzYzQ5ODlkZmM1MzU2ODJ lNWQxZGMzZjcxM2NlZTlmNGIzZDRlY2M4Y2MwMWVlNmMyMzU2Y2I1ODlhMDJkZTRkNjYzZ GViNjZlMGRkMDM5MDk3NTEwODk4NDQ3ODJjMGZkMDVjZWViNmYyYmFlNTk2NjczODg1MGR kNmRjYjY5YzEzMmFhYzg0ZWE3MDAwNGViYjUxMjcwNjViMjA2MDQwYmJmNGY2OTdlYTc5O WM2YTcxODhmNTY1MjkwOTA2YzMyNmYxYmM3OWUwMmVlMzk2MzY4MjgwZWEyMzRiODk5NzA wMmY3OWFlZjMyMWMwNjE3OTBmNjIyOGVhMTBjOGQyOTlhM2JhMjViMjk5NGM5ZTg1NjFlZ DVmNDBiODQyYWMzMTYxZGE2OWZlOWM2ZDIzZGUzNWJlMTExNjk2MmIKLS0tLS1FTkQgUEx FU0sgQURESVRJT05BTCBLRVktLS0tLQ==</license> <additional_key/> </lic_install> </server> </packet>

Response Packet Structure


The lic_install node of the response packet is structured as follows:

The result node is required. It wraps the result of the lic_install operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the lic_install operation defining whether installing key has been successfully started or not. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the lic_install operation fails. Data type: unsignedInt.

864

Supported Operations

The errtext node is optional. It returns the error message if the lic_install operation fails. Data type: string.

Response Samples
A positive response received from server looks as follows:
<packet version="1.4.2.0"> <server> <lic_install> <result> <status>ok</status> </result> </lic_install> </server> </packet>

A negative response received from server can look as follows:


<packet version="1.4.2.0"> <server> <lic_install> <result> <status>error</status> <errcode>1020</errcode> <errtext>The uploaded key file is not valid or does not contain a license key.</errtext> </result> </lic_install> </server> <output>&lt;br /&gt; &lt;b&gt;Warning&lt;/b&gt;: Key read error 2: Key test failed in &lt;b&gt;/opt/psa/admin/plib/api-rpc/AgentServer.php&lt;/b&gt; on line &lt;b&gt;195&lt;/b&gt;&lt;br /&gt; </output> </packet>

Such error is received if the request packet tried to install an invalid license key. The response packet was formed basing on the agent_output.xsd schema, that's why the output node appears.

Supported Operations

865

Getting Server Information


You can get various information about Plesk server and its configuration using Plesk API RPC protocol, that is Plesk license key data full host name detailed information on Plesk and OS versions installed on server statistics on server resources usage and Plesk logical objects (domains, clients, etc.) Administrator's personal information and settings list of supported network interfaces information on server services and their current state settings of traffic usage statistics list of shells installed on server

To retrieve any of the data listed above, use the get operation with appropriate parameter specified.

In this section:
Request Packet Structure and Samples ............................................................ 866 Response Packet Structure and Samples ......................................................... 868

866

Supported Operations

Request Packet Structure and Samples


A request XML packet retrieving information on server and Plesk configuration contains the get operation node:
<packet version="1.4.2.0"> <server> <get> ... </get> </server> </packet>

The get node is presented by complex type getType (server_input.xsd) and structured as follows:

The key node is optional. It retrieves Plesk license key. Data type: none (common.xsd). The gen_info node is optional. It retrieves general server info which is now presented by the server name. Data type: none (common.xsd). The components node is optional. It retrieves software components installed on the server and managed by Plesk. Data type: none (common.xsd).

Supported Operations

867

The stat node is optional. It retrieves Plesk and OS versions, and statistics on the server resources usage and Plesk logical objects. Data type: none (common.xsd). The admin node is optional. It retrieves Plesk Administrator's personal information and settings. Data type: none (common.xsd). The interfaces node is optional. It retrieves network interfaces supported by the server. Data type: none (common.xsd). The services_state node is optional. It retrieves current state of the server services, such as DNS service, FTP service, Mail service and so on. Data type: none (common.xsd). The prefs node is optional. It retrieves such server preferences as settings of traffic usage statistics and apache restart interval. Data type: none (common.xsd). The shells node is optional. It retrieves shells installed on the server and available for choice when configuring a domain's physical hosting. Data type: none (common.xsd). The session_setup node is optional. It retrieves session idle time, namely, the amount of time a session with Plesk should stay valid when no actions are performed. Data type: none (common.xsd).

To retrieve all server information, send a request packet with empty get node, as follows:
<packet version="1.4.2.0"> <server> <get/> </server> </packet>

To retrieve a specific information, include the corresponding child nodes to your request. For example, to retrieve currently installed components and license key, send the following request packet:
<packet version="1.4.2.0"> <server> <get> <key/> <components/> </get> </server> </packet>

To retrieve server general information, statistics and preferences, send the following request packet:
<packet version="1.4.2.0"> <server> <get> <gen_info/> <stat/> <prefs/> </get> </server> </packet>

868

Supported Operations

Response Packet Structure and Samples


The get node of the response packet is structured as follows:

The result node is required. It wraps the result of the get operation. Data type: GetResultType (server_output.xsd). The status node is required. It returns the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. Other nodes are optional, a request packet sent to a server determines if any of them present in the response packet. The key (see page 870) node returns a collection of data describing Plesk license key defining the way Plesk can be used on the server. Data type: keyType (plesk_server.xsd).

Supported Operations

869

The gen_info (see page 877) node returns a collection of data describing general server info which is now presented by the server name. Data type: serverGenInfoType (plesk_server.xsd). The components (see page 878) node returns a collection of data describing software components installed on the server and managed by Plesk. Data type: componentsType (plesk_server.xsd). The stat (see page 881) node returns a collection of data describing in detail Plesk and OS versions, and statistics on the server resources usage and Plesk logical objects. Data type: statType (plesk_server.xsd). The admin node returns a collection of data describing Plesk Administrator's personal information. Data type: adminType (plesk_server.xsd). For information on the node structure and response samples, refer to the Administrator Personal Information (see page 843) section. The interfaces (see page 891) node returns a collection of data describing network interfaces supported by the server. Data type: interfacesType (plesk_server.xsd). The services_state (see page 892) node returns a collection of data describing current state of the server services, such as DNS service, FTP service, Mail service and so on. Data type: servicesState (plesk_server.xsd). The prefs node returns a collection of data describing such server preferences as settings of traffic usage statistics and apache restart interval. Data type: serverPrefs (plesk_server.xsd). For information on the node structure and response samples, refer to the Server Preferences (see page 846) section.

The shells node returns a collection of data describing shells installed on the server and available for choosing when configuring a domain's physical hosting. Data type: ShellsList (server_output.xsd). The session_setup (see page 896) node returns session idle time, namely, the amount of time a session with Plesk should stay valid when no actions are performed. Data type: serverSessionSetup (plesk_server.xsd).

In this section:
License Key....................................................................................................... 870 General Information........................................................................................... 877 Components ...................................................................................................... 878 Server Statistics ................................................................................................ 881 Interfaces .......................................................................................................... 891 Services State ................................................................................................... 892 Shells ................................................................................................................ 894 Session Settings ............................................................................................... 896

870

Supported Operations

License Key
Starting from API RPC 1.5.0.0. there are two possible ways of retrieving license key parameters. The way used in the API RPC v.1.4.2.0 and earlier versions is parameterdependable. The other way is parameter-undependable.

In this section:
API RPC v.1.5.0.0 and Later ............................................................................. 870 API RPC v.1.4.2.0 and Earlier ........................................................................... 871

API RPC v.1.5.0.0 and Later


In the API RPC v.1.5.0.0 and later versions you should retrieve components of a license key according to the following XML schema:

The property node is required. It specifies parameters of a license key. Data type: keyType (plesk_server.xsd). The name node is required. It specifies a license key parameter name. Data type: sting. The value node is required. It specifies a license key parameter value. Data type: anySimple.

An XML response packet received from server can look as follows:


<packet version="1.5.0.0"> <server> <get> <result> <status>ok</status> <key> <property> <name>plesk_key_id</name> <value>plsk.00000000.0000</value> </property> <property> <name>product_version</name> <value>8.1</value> </property> ... </key></result></get></server></packet>

Supported Operations

871

API RPC v.1.4.2.0 and Earlier


License key properties are held by the key node represented by the complex type keyType (plesk_server.xsd). The node is structured as follows:

The plesk_key_id node is required. It returns the unique identifier of the license key installed on the server. Data type: string. The prod_type node is optional. It returns the name of the product for which the license key is created. Data type: string. Obsolete since Plesk 7.0. The lim_date node is required. It returns the date when the license key expires, in format YYYY-MM-DD. If the key never expires, the value is "0". Data type: string.

872

Supported Operations

The lim_slaves node is required. It returns the maximum number of slave Plesk servers allowed to be registered with Plesk 'Master' feature. Data type: unsignedInt. The lim_cl node is required. It returns the maximum number of Client accounts allowed on the server. Data type: string. The lim_dom node is required. It returns the maximum number of Domain accounts allowed on the server. Data type: string. The lim_mn node is required. It returns the maximum number of mail accounts allowed on the server. Data type: string. The lim_wu node is required. It returns the maximum number of Web User accounts allowed on the server. Data type: string. The MLS node is required. It returns the maximum number of additional language packs allowed on server (excluding the default English). Data type: unsignedInt. The MPCID node is required. It returns the ID of the slave server to which a request sent to the master MyPlesk.com server must be redirected. Data type: string. The noMPC node is required. It specifies if the MyPlesk.com functionality is available on the server .Data type: string. Allowed values: 0 (= the functionality is available) | 1. The noMngMPC node is required. It specifies if the Plesk Administrator is allowed to manage accessibility of the MyPlesk.com service. Data type: string. Allowed values: 0 (= allowed) | 1. The key_vz node is required. It specifies if the license key is valid only for Plesk running on Virtuozzo. Data type: short. Allowed values: 0 | 1 (only for Virtuozzo). The key_mssql node is optional. It specifies if using Microsoft SQL database is available. Data type: short. Allowed values: 0 | 1. Returned only by Plesk for Windows. The key_postgresql node is optional. It specifies if using PostgreSQL database is available. Data type: short. Allowed values: 0 | 1. Returned only by Plesk for Unix. The key_tomcat node is required. It specifies if using Tomcat is available. Data type: short. Allowed values: 0 (not available) | 1 (available). The key_gch node is required. It specifies if the Global Changes functionality (namely, group operations on objects) is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_shell node is required. It specifies if Plesk Administrator is allowed to manage shell access to the server. Data type: integer. Allowed values: 0 (not allowed) | 1 (allowed). The key_traffic node is required. It specifies if traffic usage reporting is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported by Plesk 8.0 and later. The key_cl_tmpl node is required. It specifies if the Client Template (see page 135) feature is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_notifmgr node is required. It specifies if managing server notifying system is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_eventmgs node is required. It specifies if the Event Manager feature is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_actionmgr node is required. It specifies if the Action Manager feature is available. Data type: integer. Allowed values: 0 (not available) | 1 (available).

Supported Operations

873

The key_dombackup node is required. It specifies if the backup functionality is available on the domain level. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_expiration node is required. It specifies if changing expiration date for client and domain accounts is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_subdomains node is required. It specifies if managing subdomains is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_coldfusion node is required. It specifies if using ColdFusion is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_cgitory node is required. It specifies if using the Web Applications feature is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_spamassassin node is required. It specifies if using SpamAssassin is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_expiration node is required. It specifies if changing expiration date for client and domain accounts is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_subdomains node is required. It specifies if managing subdomains is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). The key_coldfusion node is required. It specifies if using ColdFusion is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_cgitory node is required. It specifies if using the Web Applications feature is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_spamassassin node is required. It specifies if using SpamAssassin is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_drweb node is optional. It specifies if using the Dr.Web antivirus is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.5. The key_sitebuilder node is required. It specifies if using Mambo CMS is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The key_tts node is required. It specifies if using the Help Desk feature is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.0. The license_update_date node is optional. It returns the date (in format YYYYMMDD) when a grace period starts during which the license should be updated. Data type: integer. Supported from Plesk 7.5. The reseller_email node is required if the license key installed on the server is of the Reseller's type. It returns the e-mail address to which, if any problems with interaction appear, the problem description should be sent. Data type: string. Supported from Plesk 7.5.

874

Supported Operations

The key_migration node is optional. It specifies if using the Migration Manager (see page 1325) functionality is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.5. The key_askupdate node is optional. It specifies if the "License Trial Period" message should appear when admin logs in to Plesk, or not. Data type: integer. Supported from Plesk 7.5. The store_id node is optional. It returns the identification number of online shop where Plesk license key can be purchased. The default value is "1" which means the official online store on the parallels.com Web Site. Data type: integer. Supported from Plesk 7.5. The autoinstaller_config node is optional. It specifies if configuring Plesk Updater is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.5. The key_easy node is optional. It specifies if the Single Client mode is on or off. When this mode is on, all Client-related controls are missing in the control panel. Data type:integer. Allowed values: 0 (off) | 1 (on). Supported from Plesk 7.5. The key_dlu node is optional. It specifies if the Domain Administrator access to Plesk is available or not. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 7.5. The product_version node is optional. It returns the version of Plesk for which the license key is created. Data type: string. Supported from Plesk 7.5. The content node is optional. It returns the license key body. Data type: base64. The key_drweb_limit node is optional. It returns the number of mail accounts which can be filtered by the Dr.Web Antivirus for free. Data type: integer. Supported by Plesk 8.0 and later. The PLUS node is optional. It specifies if the PLUS feature is supported or not. Data type: integer. The key_manage_dashboard node is optional. It specifies if configuring Plesk Desktop is available. Data type:integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 8.0 for Unix/ Plesk 8.1 for Windows and in API RPC v.1.4.0.0 and higher. The key_stdgui node is optional. It specifies if using standard Plesk interface is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 8.0 for Unix/ Plesk 8.1 for Windows and in API RPC v.1.4.0.0 and higher. The key_dashboard node is optional. It specifies if using Plesk Desktop interface is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported from Plesk 8.0 for Unix/ Plesk 8.1 for Windows and in API RPC v.1.4.0.0 and higher. The keyserver_host node is optional. It returns the name of the Key Administrator host, with which all the license related interactions are performed. Data type: string. Supported in API RPC v.1.4.0.0 and higher. The key_ip_ranges node is required if license key restricts using Plesk by IP addresses. It returns the list of IP addresses on which using Plesk (namely, logging in to Plesk) is allowed. Data type: string. Supported in API RPC v.1.4.0.0 and higher. The key_hwid node is required if the license key is designed for Plesk running on HSPc or Virtuozzo. It returns the HWID (hardware ID) value. Data type: string. Supported in API RPC v.1.4.0.0 and higher.

Supported Operations

875

The key_qmail_queue node is optional. It specifies if managing mail queue is available. Data type: boolean. Supported from Plesk 8.0 for Unix and in API RPC v.1.4.0.0 and higher. The key_remote_db node is optional. It specifies if using remote database servers is available. Data type: boolean. Supported from Plesk 8.0 for Unix and in API RPC v.1.4.0.0 and higher. The key_newsfeeds node is optional. It specifies if the partners' news and adds are displayed in the control panel. Data type: integer. Allowed values: 0 (not displayed) | 1 (displayed). Supported in API RPC v.1.4.2.0 and higher. The lim_domain_aliases node is optional. It returns the maximum allowed number of domain aliases that can be created on the server. Data type: integer. Supported in API RPC v.1.4.2.0 and higher. The key-number node is optional. It returns the unique identifier of the license key installed on the server. Data type: int (integer). Supported in API RPC v.1.4.2.0 and higher. The key_promo_fotolia node is optional. It specifies if the links to online stock images store fotolia.com should appear in the control panel interface. Data type: integer. Allowed values: 0 (not appear) | 1 (appear). Supported in API RPC v.1.4.2.0 and higher. The key_promo_virtuozzo node is optional. It specifies if the advertisement of Virtuozzo solution should appear in the control panel interface. Data type: integer. Allowed values: 0 (not appear) | 1 (appear). Supported in API RPC v.1.4.2.0 and higher. The product-name node is optional. It specifies the name of the product for which the license key is created. Data type: string. Supported in API RPC v.1.4.2.0 and higher. The key_blog_and_photo node is optional. It defines creating blog and photogallery subdomains while crating domain account is available. Data type: integer. Allowed values: 0 (not available) | 1 (available). Supported in API RPC v.1.4.2.0 and higher; only for Plesk 8.1 for Windows and later.

876

Supported Operations

An XML response packet received from server can look as follows (the content node value was greatly reduced):
<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <key> <plesk_key_id>plsk.00000000.0000</plesk_key_id> <product_version>8.1</product_version> <lim_date>2007-03-01</lim_date> <license_update_date>20070301</license_update_date> <lim_slaves>10</lim_slaves> <lim_cl>100</lim_cl> <lim_dom>300</lim_dom> <lim_domain_aliases>300</lim_domain_aliases> <lim_mn>1000</lim_mn> <lim_wu>1000</lim_wu> <MLS>5</MLS> <MPCID>MyPlesk.com</MPCID> <noMPC>0</noMPC> <noMngMPC>0</noMngMPC> <key_easy>0</key_easy> <key_dlu>1</key_dlu> <key_vz>0</key_vz> <key_postgresql>1</key_postgresql> <key_tomcat>1</key_tomcat> <key_gch>1</key_gch> <key_shell>1</key_shell> <key_traffic>0</key_traffic> <key_cl_tmpl>1</key_cl_tmpl> <key_notifmgr>0</key_notifmgr> <key_eventmgr>0</key_eventmgr> <key_actionmgr>0</key_actionmgr> <key_dombackup>1</key_dombackup> <key_expiration>0</key_expiration> <key_subdomains>1</key_subdomains> <key_coldfusion>0</key_coldfusion> <key_cgitory>1</key_cgitory> <key_spamassassin>1</key_spamassassin> <key_sitebuilder>1</key_sitebuilder> <key_tts>0</key_tts> <key_drweb>1</key_drweb> <key_drweb_limit>15</key_drweb_limit> <key_migration>1</key_migration> <key_askupdate>0</key_askupdate> <key_newsfeeds>1</key_newsfeeds> <reseller_email>0</reseller_email> <store_id>1</store_id> <autoinstaller_config>0</autoinstaller_config> <key_dashboard>0</key_dashboard> <key_manage_dashboard>0</key_manage_dashboard> <key_stdgui>1</key_stdgui> <key_remote_db>1</key_remote_db> <keyserver_host>0</keyserver_host> <key_ip_ranges>0</key_ip_ranges> <key_hwid>0</key_hwid> <key_qmail_queue>1</key_qmail_queue> <key_promo_virtuozzo>1</key_promo_virtuozzo>

Supported Operations

877

<key_promo_fotolia>1</key_promo_fotolia> <content>LS0tLS1CRUdJTiBQTEVTSyBLRVkgREVTQ1JJUFRJT04tLS0tLQpLZXkgbnVtY mVyOiBQTFNLLjAwMDAwMDAwLjAwMDAKVGVzdCBrZXk6IHRydWUKLS0tLS1CRUdJTiBQTEV TSyBLRVktLS0tLQpNXiEwNzk6VzNXTVYtYFs7JCVGJTNCIihCJk1FKStdKTdELlxIX0g3V SE1ISElQT5cPigwKzxGUUc+NCg8Ck0vOkAtMy1cXihbTDsyPClMJUAxTDNOSlYpJSxGM0N aWSRDOSFGOj4mLjopMFE+NiZCIVcoLF9GTzU4Vk0KTUQpUjhWYFQ/VVQ1JzlMQFspQDYjT FNNTFlOVjlOWVBdV01dOV1HPD1BUDRyhcOio0NCgpNEhBQDoKTTY/RC4+OygvKDgzQVEnT lFFNkNGKEVZQS1WWzVBSCZQUyk2NTE9LU8hJS8lI08vLDdXUjY9Xi9TJl0yQwpNODI3NlR YQilCWlY9TUZbQypUNFI8TFI0PSdSV0Y8OzxAMk84RksuMDZIXy0iYFkiOU0uRSs5XFM4P CRbCk1HJzlbQEc2Lj5SRFMxVylOUlVAJUlNVS0sMEY7PyU8LVNCOzglTj1WJExVKUVYX1p LS2BMVlZGS1JeJkAKTTBQRT5FNSlFMkJOTkI6TipaXD5fQE5FOiRQIVdANktBIztVR0NOY E46Rl4kUCVURzpdNFg6PygvLU02JwpNRiNaSD9DJypdLzVBPDE9L1MxKio4VylPQEBJQVQ 5MyxYVkgiSVVbQ0whLSJFJjg+WFdHKDFfLUgsXF9GCk0rWygrNE1FNzNOM1JMIiMxQ1MrL FdALThfXCMiYDguNiM2SC9UQThVQixfUVpJXDxNN0tNPVg7QFYvXTkKTTBPRnJEpWVjJCt IXSFVSCU9TVpDWzwjUT9GUC8kJSRMOTImV0k7MFtCJE5RPTcuOyJSW0IiRFVMJygsMFI4T T1IKTxPCk1eWFAyJk9ZNio8JzMoVj45TC4zTiZKV0NRXEFDWCZeSlo7JlJdSVJJPiRHXkA iRiddTUVOQjksSz1HSFsKKCtYWkhRTUMuMSMwYApgCi0tLS0tRU5EIFBMRVNLIEtFWS0tL S0tCg==</content> </key> </result> </get> </server> </packet>

General Information
Currently, server general information include only full server name. The gen_info node of the response XML packet has the following structure:

The server_name node is required. It returns the full server name. Data type: string.

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <gen_info> <server_name>com3.johndoe.de</server_name> </gen_info> </result> </get> </server> </packet>

878

Supported Operations

Components
Detailed information on software components currently installed on a server is held by the components node. The components node of the response XML packet has the following structure:

The component node is required. It wraps the collection of data describing a particular component. Data type: none. The name node is required. It returns the software component name. Data type: string. The version node is required. It returns the detailed information on the component version, or states that the component is not installed on the server. Data type: string.

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <components> <component> <name>SSHTerm</name> <version>0.2.2-debian3.1.build81061120.18</version> </component> <component> <name>awstats</name> <version>6.4-1sarge3</version> </component> <component> <name>bind</name> <version>1:9.2.4-1sarge1</version> </component> <component> <name>coldfusion</name> <version>not_installed</version> </component> <component> <name>coldfusion-support</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>courier-imap</name> <version>3.0.8-debian3.1.build81061120.18</version>

Supported Operations </component> <component> <name>drweb</name> <version>4.33-5psa</version> </component> <component> <name>drweb-qmail</name> <version>4.33-debian3.1.build81061120.18</version> </component> <component> <name>frontpage</name> <version>not_installed</version> </component> <component> <name>httpd</name> <version>2.0.54-5sarge1</version> </component> <component> <name>mailman</name> <version>2.1.5-8sarge5</version> </component> <component> <name>mod_perl</name> <version>1.999.21-1</version> </component> <component> <name>mod_python</name> <version>3.1.3-3</version> </component> <component> <name>mysql</name> <version>4.1.11a-4sarge7</version> </component> <component> <name>perl-Apache-ASP</name> <version>2.57-3</version> </component> <component> <name>php</name> <version>4:4.3.10-16</version> </component> <component> <name>postgresql-server</name> <version>7.4.7-6sarge3</version> </component> <component> <name>psa</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-api-rpc</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-autoinstaller</name> <version>3.1.0-build31061120.17</version> </component> <component> <name>psa-backup-manager</name> <version>8.1.0-debian3.1.build81061120.18</version>

879

880

Supported Operations </component> <component> <name>psa-horde</name> <version>3.1.3-debian3.1.build81061120.18</version> </component> <component> <name>psa-imp</name> <version>4.1.3-debian3.1.build81061120.18</version> </component> <component> <name>psa-logrotate</name> <version>not_installed</version> </component> <component> <name>psa-manual-custom-skin-guide</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-migration-manager</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-mod-fcgid-configurator</name> <version>1.0-13</version> </component> <component> <name>psa-proftpd</name> <version>1.3.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-qmail</name> <version>1.03-debian3.1.build81061120.18</version> </component> <component> <name>psa-qmail-rblsmtpd</name> <version>0.70-debian3.1.build81061120.18</version> </component> <component> <name>psa-rubyrails-configurator</name> <version>1.1.6-debian3.1.build81061120.18</version> </component> <component> <name>psa-spamassassin</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-tomcat-configurator</name> <version>8.1.0-debian3.1.build81061120.18</version> </component> <component> <name>psa-turba</name> <version>2.1.3-debian3.1.build81061120.18</version> </component> <component> <name>ruby</name> <version>1.8.2-7sarge4</version> </component> <component> <name>samba</name> <version>3.0.14a-3sarge2</version>

Supported Operations </component> <component> <name>spamassassin</name> <version>3.0.3-2sarge1</version> </component> <component> <name>tomcat</name> <version>4.1.31-3</version> </component> <component> <name>webalizer</name> <version>2.01.10-26</version> </component> </components> </result> </get> </server> </packet>

881

Server Statistics
Server statistics are held by the stat node represented by the complex type statType (plesk_server.xsd). The node is structured as follows:

The objects (see page 883) node is required. It holds the collection of data describing how many Plesk objects exist on the server. Data type: objectsStatType (plesk_server.xsd). The version (see page 884) node is required. It holds the collection of data describing in detail what OS and Plesk versions are installed on the server. Data type: versionStatType (plesk_server.xsd).

882

Supported Operations

The other (see page 885) node is required. It holds the collection of data describing miscellaneous server statistics data, such as what CPU is used on the server, what is the system uptime and if the server exists within Virtuozzo. Data type: otherStatType (plesk_server.xsd). The load_avg (see page 886) node is required. It holds the collection of data describing the average usage of CPU on the server during last 1 minute, 5 and 15 minutes. Data type: load_avgStatType (plesk_server.xsd). The mem (see page 887) node is required. It holds the collection of data describing usage of physical memory on the server. Data type: memStatType (plesk_server.xsd). The swap (see page 888) node is required. It holds the collection of data describing usage of swap (virtual memory) on the server. Data type: swapStatType (plesk_server.xsd). The diskspace (see page 888) node is required. It holds the collection of data describing usage of hard disk space on the server. Data type: diskspaceStatType (plesk_server.xsd).

To see a response packet sample, go to the end of the section (see page 890).

In this section:
Plesk Objects .................................................................................................... 883 Plesk And OS Version ....................................................................................... 884 Miscellaneous Statistics .................................................................................... 885 CPU Usage ....................................................................................................... 886 Memory Usage .................................................................................................. 887 Swap Usage ...................................................................................................... 888 Disk Space Usage ............................................................................................. 888 Response Samples ........................................................................................... 890

Supported Operations

883

Plesk Objects
The objects node describing Plesk logical objects that exist on the server is presented by complex type objectsStatType (plesk_server.xsd). The node is structured as follows: The clients node is required. It returns the total number of existing Plesk client accounts. Data type: unsignedInt (integer). The domains node is required. It returns the total number of existing Plesk domain accounts. Data type: unsignedInt (integer). The active_domains node is required. It returns the number of Plesk domains that are online. Data type: unsignedInt (integer). The mail_boxes node is required. It returns the total number of existing Plesk mail boxes. Data type: unsignedInt (integer). The mail_redirects node is required. It returns the total number of mail redirects configured in Plesk. Data type: unsignedInt (integer). The mail_groups node is required. It returns the total number of mail groups. Data type: unsignedInt (integer).

The mail_responders node is required. It returns the total number of mail autoresponders existing in Plesk. Data type: unsignedInt (integer). The web_users node is required. It returns the total number of Web User accounts. Data type: unsignedInt (integer). The databases node is required. It returns the total number of all databases registered in Plesk. Data type: unsignedInt (integer). The database_users node is required. It returns the total number of all database users registered in Plesk. Data type: unsignedInt (integer). The problem_clients node is required. It returns the number of Plesk clients who exceeded their limits, for example, on traffic usage. Data type: unsignedInt (integer). The problem_domains node is required. It returns the number of domains that have exceeded the disk space and bandwidth allotments but still online. Data type: unsignedInt (integer).

884

Supported Operations

The part of the response packet returning server statistics on Plesk objects looks as follows:
<objects> <clients>32</clients> <domains>214</domains> <active_domains>198</active_domains> <mail_boxes>482</mail_boxes> <mail_redirects>53</mail_redirects> <mail_groups>27</mail_groups> <mail_responders>16</mail_responders> <web_users>327</web_users> <databases>265</databases> <database_users>265</database_users> <problem_clients>0</problem_clients> <problem_domains>0</problem_domains> </objects>

Plesk And OS Version


The version node describing what Plesk version is installed on the server is presented by complex type versionStatType (plesk_server.xsd). The node is structured as follows: The plesk_name node is required. It returns the name of the Plesk product. Data type: xs:string. The plesk_version node is required. It returns the version of Plesk installed on the server. Data type: xs:string. The plesk_os node is required. It returns the name of the operation system for which the Plesk installed on the server is designed. Data type: xs:string. The plesk_os_version node is required. It returns the version of the OS for which the Plesk installed on the server is designed. Data type: xs:string. The plesk_build node is required. It specifies what Plesk build is installed on the server. Data type: xs:string.

The os_release node is required. It returns the version of the OS kernel running on the server (for Unix/ Linux servers) or the details on OS installed on the server (for Windows servers). Data type: xs:string. The veid node is required for Plesk installed on the Virtuozzo virtual private server (VPS). It returns the VPS ID. Data type: xs:integer. Supported by API RPC v.1.4.2.0 and higher.

Supported Operations

885

The response packets parts returning information on the Plesk and operating system versions look as follows:
<version> <plesk_name>psa</plesk_name> <plesk_version>8.1.0</plesk_version> <plesk_os>Debian</plesk_os> <plesk_os_version>3.1</plesk_os_version> <plesk_build>81061120.18</plesk_build> <os_release>2.4.27-2-686</os_release> </version>

This is the part of the packet received from the server running Debian kernel v.2.4.272-686 where Plesk 8.1.0 compiled for Debian 3.1 is installed.
<version> <plesk_name>psa</plesk_name> <plesk_version>8.1.0</plesk_version> <plesk_os>FreeBSD</plesk_os> <plesk_os_version>4.11</plesk_os_version> <plesk_build>81061130.17</plesk_build> <os_release>4.11-RELEASE</os_release> </version>

This is the part of the packet received from the server running FreeBSD kernel 4.11RELEASE where Plesk 8.1.0 compiled for FreeBSD 4.11 is installed.
<version> <plesk_name>psa</plesk_name> <plesk_version>8.1.0</plesk_version> <plesk_os>Windows</plesk_os> <plesk_os_version>5.2.3790.0</plesk_os_version> <plesk_build>20061129.18</plesk_build> <os_release>Microsoft Windows 5.2;build3790;sp1.0;suite18;product3</os_release> <veid>101</veid> </version>

This is the part of the packet received from the Virtuozzo VPS with ID 101 running Microsoft Windows 2003 (base version Windows 5.2) with Service Pack 1 where Plesk 8.1.0 for Windows is installed.

Miscellaneous Statistics
The other node describing miscellaneous server statistics data is presented by complex type otherStatType (plesk_server.xsd). The node is structured as follows: The cpu node is required. It specifies what processor is used on the server. Data type: string. The uptime node is required. It specifies the amount of time (in seconds) during which the server is running. Data type: unsignedInt (integer). The inside_vz node is required. It specifies if the server is a Virtuozzo VPS or not. Data type: boolean.

886

Supported Operations

The response packets parts returning information on the Plesk and operating system versions look as follows:
<other> <cpu>AMD Sempron(tm) 2200+ x86 Family 6 Model 8 Stepping 1 ~1497MHz</cpu> <uptime>149400</uptime> <inside_vz>true</inside_vz> </other>

This is the part of the packet received from the server with AMD Sempron ~1497 MHz processor which was last time started 41 hours 30 minutes ago. The server is a Virtuozzo virtual private server.
<other> <cpu>GenuineIntel, Intel(R) Pentium(R) 4 CPU 3.00GHz</cpu> <uptime>12660</uptime> <inside_vz>false</inside_vz> </other>

This is the part of the packet received from the server with Intel Pentium 4 3.00GHz processor which was last time started about 3.5 hours ago. The server is not a Virtuozzo virtual private server.

CPU Usage
The load_avg node describing average CPU usage on the server is presented by complex type load_avgStatType (plesk_server.xsd). The node is structured as follows: The l1 node is required. It specifies the average usage of the server CPU (in %) during last minute. Data type: double. The l5 node is required. It specifies the average usage of the server CPU (in %) during last 5 minutes. Data type: double. The l15 node is required. It specifies the average usage of the server CPU (in %) during last 15 minutes. Data type: double.

The part of the response packet returning CPU usage statistics may look as follows:
<load_avg> <l1>10</l1> <l5>14</l5> <l15>9</l15> </load_avg>

Here, average server load during the last minute is 10%, last 5 minutes, 14%, and last 15 minutes, 9%.

Supported Operations

887

Memory Usage
The mem node describing physical memory usage on the server is presented by complex type memStatType (plesk_server.xsd). The node is structured as follows: The total node is required. It returns the total amount of memory (in bytes) available on the server. Data type: size (common.xsd). The used node is required. It returns the amount of memory (in bytes) being used by different processes on the server. Data type: size (common.xsd). The free node is required. It returns the amount of free memory (in bytes) available on the server. Data type: size (common.xsd). The shared node is required. It returns the size (in bytes) of the shared memory segment. Data type: size (common.xsd).

The buffer node is required. It returns the amount of memory (in bytes) used by system buffer. Data type: size (common.xsd). The cache node is required. It returns the amount of memory (in bytes) used by system cache. Data type: size (common.xsd).

The part of the response packet returning physical memory usage statistics may look as follows:
<mem> <total>2146910208</total> <used>2055024640</used> <free>91885568</free> <shared>0</shared> <buffer>0</buffer> <cached>0</cached> </mem>

888

Supported Operations

Swap Usage
The swap node describing virtual memory (swap) usage on the server is presented by complex type swapStatType (plesk_server.xsd). The node is structured as follows: The total node is required. It returns the total amount of swap (in bytes) configured on the server. Data type: size (common.xsd). The used node is required. It returns the amount of swap (in bytes) being used by different processes on the server. Data type: size (common.xsd). The free node is required. It returns the amount of free swap (in bytes) available on the server. Data type: size (common.xsd).

The part of the response packet returning swap usage statistics may look as follows:
<swap> <total>419430400</total> <used>327544832</used> <free>91885568</free> </swap>

Disk Space Usage


The diskspace node describing disk space usage on the server is presented by complex type diskspaceStatType (plesk_server.xsd). The node is structured as follows:

The device node is required. It holds the collection of data describing disk space usage on a particular partition (Windows) or device (Unix). Data type: none. Each device node has the following structure: The name node is required. It holds the partition/ device name. Data type: xs:string. The total node is required. It holds the total amount of disk space (in bytes) allocated to the partition/ device. Data type: size (common.xsd).

Supported Operations

889

The used node is required. It holds the amount of used disk space (in bytes). Data type: size (common.xsd). The free node is required. It holds the amount of free disk space (in bytes) available on the partition/ device. Data type: size (common.xsd).

The parts of the response packets returning disk space usage statistics may look as follows:
<diskspace> <device> <name>/dev/ad1s1e</name> <total>4228413440</total> <used>728193024</used> <free>3161948160</free> </device> <device> <name>/dev/ad0s1a</name> <total>2642008064</total> <used>1736767488</used> <free>693880832</free> </device> </diskspace>

This is the part of a packet received from Unix server running Plesk, where two devices ("/dev/ad1s1e" and "/dev/ad0s1a") are configured.
<diskspace> <device> <name>C:\</name> <total>3176855552</total> <used>368652288</used> <free>2808203264</free> </device> </diskspace>

This is the part of a packet received from Windows server running Plesk, where one partition (C:\) is configured.

890

Supported Operations

Response Samples
A response packet containing Plesk server statistics can look as follows:
<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <stat> <objects> <clients>32</clients> <domains>214</domains> <active_domains>198</active_domains> <mail_boxes>482</mail_boxes> <mail_redirects>53</mail_redirects> <mail_groups>27</mail_groups> <mail_responders>16</mail_responders> <web_users>327</web_users> <databases>265</databases> <database_users>265</database_users> <problem_clients>0</problem_clients> <problem_domains>0</problem_domains> </objects> <version> <plesk_name>psa</plesk_name> <plesk_version>8.1.0</plesk_version> <plesk_os>Debian</plesk_os> <plesk_os_version>3.1</plesk_os_version> <plesk_build>81061120.18</plesk_build> <os_release>2.4.27-2-686</os_release> </version> <other> <cpu>GenuineIntel, Intel(R) Pentium(R) 4 CPU 3.00GHz</cpu> <uptime>12660</uptime> <inside_vz>false</inside_vz> </other> <load_avg> <l1>10</l1> <l5>14</l5> <l15>9</l15> </load_avg> <mem> <total>2146910208</total> <used>2055024640</used> <free>91885568</free> <shared>0</shared> <buffer>0</buffer> <cached>0</cached> </mem> <swap> <total>419430400</total> <used>327544832</used> <free>91885568</free> </swap> <diskspace> <device> <name>/dev/ad1s1e</name>

Supported Operations <total>4228413440</total> <used>728193024</used> <free>3161948160</free> </device> <device> <name>/dev/ad0s1a</name> <total>2642008064</total> <used>1736767488</used> <free>693880832</free> </device> </diskspace> </stat> </result> </get> </server> </packet>

891

Interfaces
A list of network interfaces supported by a server is held by the interfaces node of the response XML packet. The node has the following structure:

The interface node is required. It contains the name of a particular network interface. Data type: netInterfacesType (plesk_common.xsd).

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <interfaces> <interface>eth0</interface> </interfaces> </result> </get> </server> </packet>

892

Supported Operations

Services State
Information on the server services, such as DNS service, FTP service, Mail service and so on, and their current state is held by the services_state node, which is presented by complex type servicesState (plesk_server.xsd). The node is structured as follows:

The srv node is required. It wraps the collection of data describing particular service . Data type: none. The id node is required. It holds the service identifier. Data type: string. The title node is required. It holds the service name. Data type: string. The state node is required. It holds the current state of the service. Data type: string. Allowed values: running | stopped | none. The error node is required if an error occurred while the service running. The node contains the text of the service error. Data type: string.

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <services_state> <srv> <id>web</id> <title>Web Server (Apache)</title> <state>running</state> </srv> <srv> <id>smtp</id> <title>SMTP Server (QMail)</title> <state>running</state> </srv> <srv> <id>mail</id> <title>IMAP/POP3 Server (Courier-IMAP)</title> <state>running</state> </srv>

Supported Operations <srv> <id>dns</id> <title>DNS Server (BIND)</title> <state>running</state> </srv> <srv> <id>tomcat</id> <title>Tomcat</title> <state>running</state> </srv> <srv> <id>coldfusion</id> <title>ColdFusion (Not configured)</title> <state>none</state> </srv> <srv> <id>postgresql</id> <title>PostgreSQL</title> <state>stopped</state> </srv> <srv> <id>spamassassin</id> <title>SpamAssassin</title> <state>running</state> </srv> <srv> <id>drweb</id> <title>Dr.Web antivirus</title> <state>stopped</state> </srv> </services_state> </result> </get> </server> </packet>

893

894

Supported Operations

Shells
The meaning of the shell node depends on whether we are talking about Plesk for Unix or Plesk for Windows. In the case of Plesk for Unix, the shell node returns a list of shells installed on the server and available for choosing when configuring a domain physical hosting (see page 409), on the step of allowing shell access. In the case of Plesk for Windows, the shell node returns only the values of the shell access parameter of the domain physical hosting (see page 409). The node has the following structure:

Plesk for Unix The shell node is required. It wraps a collection of data describing a particular shell. Data type: shellType (plesk_server.xsd). The name node is required. It specifies the shell's name as it is displayed in Plesk GUI on the page of physical hosting setup. Data type: string. The path node is required. It specifies the full pass to the shell. Data type: string.

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <shells> <shell> <name>Forbidden</name> <path>/bin/false</path> </shell> <shell> <name>/bin/bash</name> <path>/bin/bash</path> </shell> <shell> <name>/bin/sh</name> <path>/bin/sh</path> </shell> <shell> <name>/usr/bin/ksh</name> <path>/usr/bin/ksh</path> </shell>

Supported Operations <shell> <name>/bin/ksh</name> <path>/bin/ksh</path> </shell> <shell> <name>/usr/bin/zsh</name> <path>/usr/bin/zsh</path> </shell> <shell> <name>/bin/zsh</name> <path>/bin/zsh</path> </shell> <shell> <name>/bin/rbash</name> <path>/bin/rbash</path> </shell> <shell> <name>/bin/dash</name> <path>/bin/dash</path> </shell> <shell> <name>/bin/bash (chrooted)</name> <path>/opt/psa/bin/chrootsh</path> </shell> </shells> </result> </get> </server> </packet>

895

Plesk for Windows The shell node is required. It wraps a collection of data describing a particular value of the 'shell access' parameter. Data type: shellType (plesk_server.xsd). The name node is required. It specifies the 'shell access' parameter value as it is displayed in Plesk GUI on the page of physical hosting setup. Data type: string. The path node is required. It specifies the 'shell access' parameter value as it is displayed in Plesk GUI on the page of physical hosting setup. Data type: string.

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <shells> <shell> <name>Login disabled</name> <path>Login Disabled</path> </shell> <shell> <name>Login enabled</name> <path>Login Enabled</path> </shell> </shells> </result> </get>

896

Supported Operations </server> </packet>

Note: If received from server running Plesk for Windows, the response packet always looks like the example above.

Session Settings
Settings of the user's Plesk GUI session are held by the session_setup node of the response XML packet. The node has the following structure:

The login_timeout node is optional. It returns the period (in minutes) during which the user's session can idle before it is automatically closed by the server. Data type: int (integer). Allowed values: 1 to 99999.

A response packet received from server can look as follows:


<packet version="1.4.2.0"> <server> <get> <result> <status>ok</status> <session_setup> <login_timeout>30</login_timeout> </session_setup> </result> </get> </server> </packet>

Supported Operations

897

Setting Up Server
Using the set operation, one can Change Administrator's password Change Administrator's personal info (see page 843) Set up server preferences (see page 846) Set up session settings, namely, session timeout

In this section:
Request Packet Structure.................................................................................. 898 Request Samples .............................................................................................. 899 Response Packet Structure ............................................................................... 900 Response Samples ........................................................................................... 900

898

Supported Operations

Request Packet Structure


A request XML packet changing Plesk server settings or Administrator's information contains the set operation node:
<packet version="1.4.2.0"> <server> <set> ... </set> </server> </packet>

The set node is presented by complex type AdminSetType (server_input.xsd) and structured as follows:

The admin node is optional. It wraps the collection of data describing Administrator's personal information and settings. Data type: adminType (plesk_server.xsd). For information on the node structure and request packet samples, refer to the Administrator Personal Information (see page 843) section. The password node is optional. It specifies new Plesk Administrator's password (5 to 14 characters). Data type: serverPassword (plesk_server.xsd). The prefs node is optional. It wraps the collection of data describing traffic usage statistics settings and Apache restart interval. Data type: serverPrefs (plesk_server.xsd). For information on the node structure and request packet samples, refer to the Server Preferences (see page 846) section. The session_setup node is optional. It holds data describing settings of the user's session in Plesk. Data type: serverSessionSetup (plesk_server.xsd). The login_timeout node is optional. It returns the period (in minutes) during which the user's session can idle before it is automatically closed by the server. Data type: integer. Allowed values: 1 to 99999.

Despite all child elements of the set node are optional, the all model group is used, which means that the request packet must contain the set node with at least one child node.

Supported Operations

899

Request Samples
This packet changes Administrator's personal information and password.
<packet version="1.4.2.0"> <server> <set> <admin> <admin_cname>JohnDoe BV.</admin_cname> <admin_pname>John Doe</admin_pname> <admin_phone>+49 89333333</admin_phone> <admin_fax>+49 893333303</admin_fax> <admin_email>john@doe.de</admin_email> <admin_address>Theatinerstrasse 96</admin_address> <admin_city>Muenchen</admin_city> <admin_state>Bavaria</admin_state> <admin_pcode>80333</admin_pcode> <admin_country>DE</admin_country> <send_announce>true</send_announce> </admin> <password>gogo4ward</password> </set> </server> </packet>

This packet configures server traffic usage statistics so that both inbound and outbound traffic is logged and the log is stored during 3 months; Apache should not restart automatically; session timeout is 30 minutes.
<packet version="1.4.2.0"> <server> <set> <prefs> <stat_ttl>3</stat_ttl> <traffic_accounting>3</traffic_accounting> <restart_apache_interval>0</restart_apache_interval> </prefs> <session_setup> <login_timeout>30</login_timeout> </session_setup> </set> </server> </packet>

900

Supported Operations

Response Packet Structure


The set node of the response packet is structured as follows:

The result node is required. It wraps the result of the set operation. Data type: SetResultType (server_output.xsd). The status node is required. It returns the execution status of the set operation defining whether server configuration or administrator's information were successfully updated or not. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the set operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the set operation fails. Data type: string.

Response Samples
A positive response received from server looks as follows:
<packet version="1.4.2.0"> <server> <set> <result> <status>ok</status> </result> </set> </server> </packet>

Supported Operations

901

Managing Plesk Services


Server services, such as mail service, DNS service, FTP and so on, can be started, stopped and restarted via both Plesk GUI and Plesk API RPC protocol. To start, stop or restart a particular service, use the srv_man operation. To get information on the current state of the server services (whether each is started or stopped at the moment), use the get (see page 864) operation with services_state (see page 892) parameter specified.

In this section:
Request Packet Structure.................................................................................. 901 Request Samples .............................................................................................. 902 Response Packet Structure ............................................................................... 903 Response Samples ........................................................................................... 904

Request Packet Structure


A request XML packet starting, stopping or restarting server services contains the srv_man operation node:
<packet version="1.4.2.0"> <server> <srv_man> ... </srv_man> </server> </packet>

The srv_man node is presented by complex type ServicesManagementType (server_input.xsd) and structured as follows:

The id node is required. It specifies the ID of the service that should be started/ restarted/ stopped. Data type: srvIdType (plesk_server.xsd). The operation node is required. It specifies what should be done to the server specified by the id node. Data type: srvOpType (plesk_server.xsd). Allowed values: start | stop | restart.

902

Supported Operations

Request Samples
This packet stops the web service (Apache on server running Unix).
<packet version="1.4.2.0"> <server> <srv_man> <id>web</id> <operation>stop</operation> </srv_man> </server> </packet>

This packet restarts all mail services running on the server, namely, MailEnable List Connector, MailEnable Mail Transfer Agent, MailEnable Postoffice Connector, MailEnable POP Service and MailEnable SMTP Connector.
<packet version="1.4.2.0"> <server> <srv_man> <id>MELCS</id> <operation>restart</operation> <id>MEMTAS</id> <operation>restart</operation> <id>MEPOCS</id> <operation>restart</operation> <id>MEPOPS</id> <operation>restart</operation> <id>MESMTPCS</id> <operation>restart</operation> </srv_man> </server> </packet>

This packet starts PostgreSQL and MySQL database services.


<packet version="1.4.2.0"> <server> <srv_man> <id>postgresql</id> <operation>start</operation> <id>mysql</id> <operation>start</operation> </srv_man> </server> </packet>

Supported Operations

903

Response Packet Structure


The srv_man node of the response packet is structured as follows:

The result node is required. It wraps the result of the srv_man operation. Data type: ServicesManagementResultType (server_output.xsd). The status node is required. It returns the execution status of the srv_man operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the srv_man operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the srv_man operation fails. Data type: string. The id node is required if the srv_man operation succeeds. It returns the ID of the service which was successfully started, stopped or restarted. Data type: srvIdType (plesk_server.xsd).

904

Supported Operations

Response Samples
Positive responses received from server look as follows:
<packet version="1.4.2.0"> <server> <srv_man> <result> <status>ok</status> <id>web</id> </result> </srv_man> </server> </packet>

<packet version="1.4.2.0"> <server> <srv_man> <result> <status>ok</status> <id>postgresql</id> <id>mysql</id> </result> </srv_man> </server> </packet>

Negative responses received from server look like below:


<packet version="1.4.2.0"> <server> <srv_man> <result> <status>error</status> <errcode>1026</errcode> <errtext>Service coldfusion is not installed</errtext> <id>coldfusion</id> </result> </srv_man> </server> </packet>

Such error is received if the request packet tried to perform an operation on the service which is not installed on the server.
<packet version="1.4.2.0"> <server> <srv_man> <result> <status>error</status> <errcode>1013</errcode> <errtext>service does not exist</errtext> <id>Plesk</id> </result> </srv_man></server></packet>

Such error is received if the request packet tried to perform an operation on the service which does not exist.

Supported Operations

905

Managing Plesk Updates


Operator: <updater> XML Schema: updater.xsd Plesk version: 8.1.1 API RPC version: 1.5.0.0 Plesk user: Plesk Administrator Description The updater operator is used to manage Plesk updates and install specified components. This operator generalizes methods of working with Plesk updates system. Full functionality is available in Plesk for Unix. In Plesk for Windows functionality of the operator is limited. For instance, you cannot install specified components - this task is made by Plesk Installer.

In this section:
Checking Updater Status ...................................................................................906 Retrieving Plesk Updates ...................................................................................908 Retrieving Components List ...............................................................................911 Installing Components .......................................................................................915 Updating Plesk...................................................................................................919

Supported operations

CHECK (on page 906) shows current status of Plesk Updater GET-UPDATES (on page 908) retrieves list of available Plesk updates

906

Supported Operations

GET-COMPONENTS (on page 911) checks status of already installed components, and retrieves list of new components available for installation INSTALL-COMPONENT (on page 915) installs the specified component UPDATE (on page 919) updates current version of Plesk

Checking Updater Status


The check operation is used to show current status of Plesk Updater. If it is installing a component or updating Plesk, the other operations are unavailable.

In this section:
Request Packet ................................................................................................. 906 Response Packet Structure ............................................................................... 906 Response Samples ........................................................................................... 908

Request Packet
A request XML packet retrieving status of Plesk Updater includes the check operation node:
<packet version="1.5.0.0"> <updater> <check/> </updater> </packet>

The check node is required. Data type: none.

Supported Operations

907

Response Packet Structure


The check node of the output XML packet is presented by type UpdaterCheckOutputType (updater.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type:resultType (common.xsd). The status node is required. It specifies if the Plesk Updater is not busy. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the check operation fails. Data type: integer. The errtext node is optional. It returns the error message if the check operation fails. Data type: string.

908

Supported Operations

Response Samples
If Plesk Updater is not busy, the response packet from the server will look as follows:
<packet version="1.5.0.0"> <updater> <check> <result> <status>ok</status> </result> </check> </updater> </packet>

If Plesk Updater is busy, the response packet from the server will look as follows:
<packet version="1.5.0.0"> <updater> <check> <result> <status>error</status> <errcode>1035</errcode> <errtext>Service is busy</errtext> </result> </check> </updater> </packet>

Retrieving Plesk Updates


The get-updates operation is used to show list of available Plesk updates. In Plesk for Unix this operation retrieves the current release if there are no updates.

In this section:
Request Packet ................................................................................................. 909 Response Packet Structure ............................................................................... 909 Response Samples ........................................................................................... 910

Supported Operations

909

Request Packet
A request XML packet retrieving Plesk updates includes the get-updates operation node:
<packet version="1.5.0.0"> <updater> <get-updates/> </updater> </packet>

The get-updates node is required. Data type: none.

Response Packet Structure


The get-updates node of the output XML packet is presented by type UpdaterGetUpdatesOutputType (updater.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-updates operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-updates operation fails. Data type: string.

910

Supported Operations

The update node is optional. It holds available Plesk updates. Data type: UpdateType (updater.xsd).

If the update node is present in the response packet, the following nodes are required: The id node specifies the update ID. Data type: string. The action node specifies what to do with the update. If the update is not installed, the action will be equal to install. If it was installed, but some components have changed since that moment, the action node will be equal to update. The unknown value is reserved for actions that are not supported in the current version of the protocol. The up2day value marks current Plesk release in Plesk for Unix. If the action value is upgrade, you can upgrade to the next major version. Data type: string. Allowed values: install (in Plesk for Unix only) | update | upgrade | up2date | unknown. The description node holds a brief description of the update. Data type: string.

Response Samples
In Plesk for Unix, a possible response from the server can look as follows:
<?xml version="1.0" encoding="UTF-8"?> <packet version="1.5.0.0"> <updater> <get-updates> <result> <status>ok</status> <update> <id>PLESK_8_1_1</id> <action>up2date</action> <description>Plesk 8.1.1</description> </update> </result> </get-updates> </updater> </packet>

Supported Operations

911

Retrieving Components List


The get-components operation is used in the following situations: to retrieve list of available for installation components to check status of already installed components

Note: This operation is supported only in Plesk for Unix.

In this section:
Request Packet ................................................................................................. 912 Response Packet Structure ............................................................................... 913 Response Samples ........................................................................................... 915

912

Supported Operations

Request Packet
A request XML packet retrieving status of Plesk Updater includes the get-components operation node:
<packet version="1.5.0.0"> <updater> <get-components> ... </get-components> </updater> </packet>

The graphical representation of the get-components node is as follows:

The update-id node is required. It specifies the update ID. For info on how to retrieve the update ID, refer to the Retrieving Plesk Updates (on page 908) section. Data type: string.

Request sample This request packet retrieves components of the update with ID 8.
<packet version="1.5.0.0"> <updater> <get-components> <update-id>PLESK_8_1_1</update-id> </get-components> </updater> </packet>

Supported Operations

913

Response Packet Structure


The get-components node of the output XML packet is presented by type UpdaterGetComponentsOutputType (updater.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-components operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-components operation fails. Data type: string. The component node is optional. It holds info on new and existing components. Data type: ComponentType (updater.xsd).

914

Supported Operations

If the component node is present in the response packet, the following nodes are required: The id node specifies the component ID. Data type: string. The action node specifies what to do with the component. It can be installed or upgraded. The unknown value is reserved for actions that are not supported in the current version of the protocol. The up2day value tells that component is up to date. Data type: string. Allowed values: install | upgrade | up2date | unknown. The description node holds a brief description of the component. Data type: string. The server-build-time node specifies time of last build of the version containing the component. Here we consider version of Plesk on the update server. Data type: timestamp. The local-build-time node specifies time of last build of the version containing the component. Here we consider version of Plesk on your server. The server-version node specifies Plesk version on the update server. Data type: string. The local-version node specifies your current Plesk version. Data type: string.

Supported Operations

915

Response Samples
A possible response from the server can look as follows:
<packet version="1.5.0.0"> <updater> <get-components> <result> <status>ok</status> <component> <id>base</id> <action>upgrade</action> <description>Base packages of Plesk</description> <server-build-time>1172072935</server-build-time> <local-build-time>1171899420</local-build-time> <server-version>8.1.1-suse9.3.build81070219.20</serverversion> <local-version>8.1.1-suse9.3.build81070221.20</localversion> </component> ... <id>ja-JP-locale</id> <action>up2date</action> <description>Japanese language pack</description> <server-build-time>1171545168</server-build-time> <local-build-time>1171545168</local-build-time> <server-version>8.1-build81070215.19</server-version> <local-version>8.1-build81070215.19</local-version> </component> </result> </get-components> </updater> </packet>

916

Supported Operations

Installing Components
The install-component operation is used to install specified components to your Plesk server. Note: This operation is supported only in Plesk for Unix.

In this section:
Request Packet Structure.................................................................................. 916 Request Samples .............................................................................................. 917 Response Packet Structure ............................................................................... 917 Response Samples ........................................................................................... 918

Request Packet Structure


A request XML packet installing Plesk components includes the install-component operation node:
<packet version="1.5.0.0"> <updater> <install-component> ... </install-component> </updater> </packet>

The graphical representation of the install-component node is as follows:

The update-id node is required. It specifies the update ID. For info on how to retrieve the update ID, refer to the Retrieving Plesk Updates (on page 908) section. Data type: string. The component-id node is required. It specifies the component ID. For info on how to retrieve the component ID, refer to the Retrieving Plesk Components List (on page 911) section. Data type: string.

Supported Operations

917

Request Samples
The following request packet upgrades the ColdFusion support for Plesk:
<packet version="1.5.0.0"> <updater> <install-component> <update-id>PLESK_8_1_1</update-id> <component-id>cf-support</component-id> </install-component> </updater> </packet>

The following request packet upgrades the SiteBuilder publishing support for Plesk:
<packet version="1.5.0.0"> <updater> <install-component> <update-id>PLESK_8_1_1</update-id> <component-id>sb-publish</component-id> </install-component> </updater> </packet>

Response Packet Structure


The install-component node of the output XML packet is presented by type UpdaterInstallComponentOutputType (updater.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the install-component operation fails. Data type: integer.

918

Supported Operations

The errtext node is optional. It returns the error message if the install-component operation fails. Data type: string.

Response Samples
Request packet sample The following request packet upgrades the ColdFusion support for Plesk:
<packet version="1.5.0.0"> <updater> <install-component> <update-id>PLESK_8_1_1</update-id> <component-id>cf-support</component-id> </install-component> </updater> </packet>

Response packet samples A positive response from the server looks as follows:
<packet version="1.5.0.0"> <updater> <install-component> <result> <status>ok</status> </result> </install-component> </updater> </packet>

If Plesk Auto-Installer is busy, the response packet from the server will look as follows:
<packet version="1.5.0.0"> <updater> <install-component> <result> <status>error</status> <errcode>1035</errcode> <errtext>Service is busy</errtext> </result> </install-component> </updater> </packet>

Supported Operations

919

Updating Plesk
The update operation is used to update your Plesk server. All components from a specified update will be affected.

In this section:
Request Packet ................................................................................................. 919 Response Packet Structure ............................................................................... 920 Response Samples ........................................................................................... 921

Request Packet
A request XML packet updating Plesk includes the update operation node:
<packet version="1.5.0.0"> <updater> <update> ... </update> </updater> </packet>

The graphical representation of the update node is as follows:

The update-id node is required. It specifies the update ID. For info on how to retrieve the update ID, refer to the Retrieving Plesk Updates (on page 908) section. Data type: string.

Request sample This request updates Plesk to 8.1.1 version.


<packet version="1.5.0.0"> <updater> <update> <update-id>PLESK_8_1_1</update-id> </update> </updater> </packet>

920

Supported Operations

Response Packet Structure


The update node of the output XML packet is presented by type UpdaterUpdateOutputType (updater.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the update operation fails. Data type: integer. The errtext node is optional. It returns the error message if the update operation fails. Data type: string.

Supported Operations

921

Response Samples
Request packet sample This request updates Plesk to 8.1.1 version.
<packet version="1.5.0.0"> <updater> <update> <update-id>PLESK_8_1_1</update-id> </update> </updater> </packet>

Response packet samples A positive response from the server looks as follows:
<packet version="1.5.0.0"> <updater> <update> <result> <status>ok</status> </result> </update> </updater> </packet>

If Plesk Auto-Installer is busy, the response packet from the server will look as follows:
<packet version="1.5.0.0"> <updater> <update> <result> <status>error</status> <errcode>1035</errcode> <errtext>Service is busy</errtext> </result> </update> </updater> </packet>

922

Supported Operations

Managing Protected Directories


Operator: <protected_dir> XML Schema: protected_dir.xsd Plesk version: Plesk 8.3 for Unix and later | Plesk 8.3 for WIndows and later API RPC version: 1.5.2.0 Plesk user: Plesk Administrator, Plesk client Description For storing sensitive data, you can create password-protected directories within domains on physical hosting. It is possible to create such directories under either a standard virtual host accessible via HTTP protocol, or if applicable for a given particular domain, under an SSL virtual host accessible via HTTPs protocol.

In this section:
Filtering Issues .................................................................................................. 923 Creating Protected Directory ............................................................................. 925 Changing Protected Directory Properties .......................................................... 930 Removing Protected Directory ........................................................................... 938 Retrieving Protected Directory Properties .......................................................... 942 Creating Protected Directory User ..................................................................... 948 Changing Protected Directory User Settings ..................................................... 951 Removing Protected Directory User .................................................................. 957 Retrieving Protected Directory User Settings..................................................... 960 Retrieving Descriptor of Protected Directory Properties ..................................... 965 Supported operations

Supported Operations

923

ADD (on page 925) creates a protected directory SET (on page 930) changes protected directory properties DELETE (on page 938) removes a protected directory ADD-USER (on page 948) creates a new protected directory user SET-USER (on page 951) changes protected directory user preferences DELETE-USER (on page 957) removes a protected directory user GET (on page 942) retrieves information about a protected directory GET-USER (on page 960) retrieves information about a protected directory user GET-PD-LOCATION-DESCRIPTOR (on page 965) retrieves a protected directory descriptor

Filtering Issues
Filtering is the way the request XML packet indicates the object to which an operation will be applied. The request XML packet filters objects using a special <filter> section. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

In this section:
ProtectedDirFilter Filter ..................................................................................... 923 ProtectedDirUserFilter Filter .............................................................................. 924 filter-id Node ...................................................................................................... 925

ProtectedDirFilter Filter
The ProtectedDirFilter filter is used in delete, set and get operations. For more information on the operations, refer to the Removing Protected Directory (on page 938), Changing Protected Directory Properties (on page 930), Retrieving Protected Directory Properties (on page 942) sections. Data type:ProtectedDirFilter (protected_dir.xsd). The graphical representation of the filter node is as follows:

The id node is optional. It specifies the ID of the protected directory. Data type: integer.

924

Supported Operations

The domain-id node is optional. It specifies the ID of the domain containing protected directories. Use this parameter to match all protected directories of a specific domain. Data type: integer. The domain-name node is optional. It specifies the name of the domain containing the protected directories. Use this parameter to match all protected directories of a specific domain. Data type: string.

Remarks You can match protected directories for multiple domains as in the following example:
<filter> <domain-id>122</domain-id> <domain-id>292</domain-id> </filter>

You can match multiple protected directories by IDs as in the following example:
<filter> <id>22</id> <id>92</id> </filter>

Note: Use the blank filter (<filter/>) to match all protected directories available for a packet sender.

ProtectedDirUserFilter Filter
The ProtectedDirUserFilter filter is used in delete-user, set-user and get-user operations. For more information on the operations, refer to the Removing Protected Directory User (on page 957), Changing Protected Directory User Settings (on page 951), Retrieving Protected Directory User Settings (on page 960) sections. Data type:ProtectedDirUserFilter (protected_dir.xsd). The graphical representation of the filter node is as follows:

The pd-id node is optional. It specifies the ID of the protected directory. Data type: integer. The id node is optional. It specifies the protected directory user ID. Data type: integer.

Supported Operations

925

Remarks You can match multiple protected directory users by IDs as in the following example:
<filter> <id>122</id> <id>292</id> </filter>

You can match multiple protected directories by IDs as in the following example:
<filter> <pd-id>22</pd-id> <pd-id>92</pd-id> </filter>

Note: Use the blank filter (<filter/>) to match all protected directory users available for a packet sender.

filter-id Node

If an operation uses filters in a request packet, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule, it is returned in the filter-id node of the response packet. ID of a protected directory ID of a protected directory user Domain ID Domain name

It is done to trace the request parameters in case of an error. Data type: anySimple. Note: If a request packet uses blank filter (<filter/>), the ID of the object affected by the operation will be is set as the value for the filter-id node. The object ID is the protected directory ID for operations on protected directories, and it is the protected directory user ID for operations on the users. All operations except for the add and add-user possess the filter-id node in the response packet.

926

Supported Operations

Creating Protected Directory


Use the add operation to add a new protected directory.

In this section:
Request Packet Structure.................................................................................. 926 Request Samples .............................................................................................. 927 Response Packet Structure ............................................................................... 928 Response Samples ........................................................................................... 929

Request Packet Structure


A request XML packet adding a new protected directory includes the add operation node:
<packet version="1.5.2.0"> <protected_dir> <add> ... </add> </protected_dir> </packet>

The add node is presented by the ProtectedDirAddInput type (protected_dir.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain on which the protected directory is created. Data type: integer. The name node is required. It specifies the protected directory name. Data type: string. The header node is optional. It specifies the protected directory header. It is the message that is displayed to a user when he tries to access the protected directory. Data type: string.

Supported Operations

927

The location node is optional. It specifies protected directory properties. Data type: complex.

Note: The location node can be specified only in Plesk for Linux/Unix. The SSL support parameter is inherited from settings of the domain: If it is enabled on the domain, it will also be enabled for the protected directory. If the node is not present in the request packet, the protected directory will be created with default settings ssl=true/false (depending on domain settings), nonssl=true and cgi=false. The property node is required if the location node is specified. It specifies the protected directory property. You cannot disable all protected directory properties. At least one value should be true after performing the add operation. Data type: ProtectedDirLocationProperty (protected_dir.xsd). The name node is required if the location node is specified. It specifies the protected directory property name. Data type: string. The value node is required if the location node is specified. It specifies the protected directory property value. Data type: boolean.

Request Samples
The following request packet creates MyDirectory protected directory on the domain with ID 1. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <add> <domain-id>1</domain-id> <name>MyDirectory</name> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </add> </protected_dir> </packet>

928

Supported Operations

The following request packet creates MyDirectory protected directory on the domain with ID 1. The packet is valid only in Plesk for Windows.
<packet version="1.5.2.0"> <protected_dir> <add> <domain-id>1</domain-id> <name>MyDirectory</name> <header>This is a header!</header> </add> </protected_dir> </packet>

Response Packet Structure


The add node of the output XML packet is presented by type ProtectedDirAddOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The id node is required if the operation succeeds. It returns the ID of the added protected directory. Data type: integer.

Supported Operations

929

Response Samples
The following request packet creates MyDirectory protected directory on the domain with ID 1. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <add> <domain-id>1</domain-id> <name>MyDirectory</name> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </add> </protected_dir> </packet>

A positive response from the server looks as follows:


<packet version="1.5.2.0"> <protected_dir> <add> <result> <status>ok</status> <id>1</id> </result> </add> </protected_dir> </packet>

If domain was not found, the response is as follows:


<packet version="1.5.2.0"> <protected_dir> <add> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain is not found</errtext> </result> ... </add> </protected_dir> </packet>

930

Supported Operations

If MyDirectory directory already exists, the response is as follows:


<packet version="1.5.2.0"> <protected_dir> <add> <result> <status>error</status> <errcode>1007</errcode> <errtext>URL with name 'name' already exists</errtext> </result> ... </add> </protected_dir> </packet>

Changing Protected Directory Properties


Use the set operation to change protected directory properties.

In this section:
Request Packet Structure.................................................................................. 930 Request Samples .............................................................................................. 932 Response Packet Structure ............................................................................... 934 Response Samples ........................................................................................... 935

Request Packet Structure


A request XML packet changing protected directory properties includes the set operation node:
<packet version="1.5.2.0"> <protected_dir> <set> ... </set> </protected_dir> </packet>

The set node is presented by type ProtectedDirAddInput (protected_dir.xsd), and its graphical representation is as follows:

Supported Operations

931

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 923) section. Data type: ProtectedDirFilter (protected_dir.xsd). The values node is required. It specifies the protected directory properties. The node is presented by type ProtectedDir (protected_dir.xsd). Its graphical representation is as follows:

The name node is optional. It specifies the protected directory name. Data type: string. The header node is optional. It specifies the protected directory header. It is the message that is displayed to a user when he tries to access the protected directory. Data type: string. The location node is optional. It specifies protected directory properties. The location node can be specified only in Plesk for Linux/Unix. Data type: complex. The property node is required if the location node is specified. It specifies the protected directory property. You cannot disable all protected directory properties. At least one value should be true after performing the set operation. Data type: ProtectedDirLocationProperty (protected_dir.xsd). The name node is required if the location node is specified. It specifies the protected directory property name. Data type: string. Names and values of properties that can be changed for a specific domain or common for all domains properties can be retrieved using the get-pd-location-descriptor operation. The value node is required if the location node is specified. It specifies the protected directory property value. Data type: boolean.

932

Supported Operations

Request Samples
Changing properties of a single protected directory The following packet changes properties of the protected directory with ID 1. The packet is valid only in Plesk for Windows.
<packet version="1.5.2.0"> <protected_dir> <set> <filter> <id>1</id> </filter> <values> <header>This is a header!</header> </values> </set> </protected_dir> </packet>

The following packet changes properties of the protected directory with ID 1. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <set> <filter> <id>1</id> </filter> <values> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </values> </set> </protected_dir> </packet>

Supported Operations

933

Changing properties of multiple protected directories The following packet changes properties of all protected directories on the domain with ID 1. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <set> <filter> <domain-id>1</domain-id> </filter> <values> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </values> </set> </protected_dir> </packet>

The following packet changes properties of protected directories on example.com domain. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <set> <filter> <domain-name>example.com</domain-name> </filter> <values> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </values> </set> </protected_dir></packet>

934

Supported Operations

The following packet changes properties of all protected directories available for a packet sender. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <set> <filter/> <values> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </values> </set> </protected_dir> </packet>

Response Packet Structure


The set node of the output XML packet is presented by type ProtectedDirSetOutput (protected_dir.xsd) and structured as follows:

Supported Operations

935

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is required if the operation succeeds. It returns the ID of the protected directory which properties were changed. Data type: integer.

Response Samples
Changing properties of a single protected directory The following packet changes properties of the protected directory with ID 1. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <set> <filter> <id>1</id> </filter> <values> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </values> </set> </protected_dir> </packet>

936

Supported Operations

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <protected_dir> <set> <result> <status>ok</status> <filter-id>1</filter-id> <id>1</id> </result> </set> </protected_dir> </packet>

If the directory was not found, the response from the server is as follows:
<packet version="1.5.2.0"> <protected_dir> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Protected URL is not found</errtext> <filter-id>1</filter-id> </result> </set> </protected_dir> </packet>

If invalid header text was specified in the request packet, the response from the server looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set> <result> <status>error</status> <errcode>1019</errcode> <errtext>Invalid value for 'header' specified</errtext> <filter-id>1</filter-id> </result> </set> </protected_dir> </packet>

Supported Operations

937

Changing properties of multiple protected directories The following packet changes properties of all protected directories available for a packet sender. The packet is valid only in Plesk for Linux/Unix.
<packet version="1.5.2.0"> <protected_dir> <set> <filter/> <values> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>nonssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> </location> </values> </set> </protected_dir> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <set> <result> <status>ok</status> <filter-id>1</filter-id> <id>1</id> </result> <result> <status>ok</status> <filter-id>2</filter-id> <id>2</id> </result> </set> </protected_dir> </packet>

938

Supported Operations

Removing Protected Directory


Use the delete operation to remove a protected directory.

In this section:
Request Packet Structure.................................................................................. 938 Request Samples .............................................................................................. 939 Response Packet Structure ............................................................................... 939 Response Samples ........................................................................................... 941

Request Packet Structure


A request XML packet removing a protected directory includes the delete operation node:
<packet version="1.5.2.0"> <protected_dir> <delete> ... </delete> </protected_dir> </packet>

The delete node is presented by type ProtectedDirDelInput (protected_dir.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 923) section. Data type: ProtectedDirFilter (protected_dir.xsd).

Supported Operations

939

Request Samples
The packet that removes the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <delete> <filter> <id>1</id> </filter> </delete> </protected_dir> </packet>

The packet that removes all protected directories from domain with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <delete> <filter> <domain-id>1</domain-id> </filter> </delete> </protected_dir> </packet>

The packet that removes all protected directories from example.com domain looks as follows:
<packet version="1.5.2.0"> <protected_dir> <delete> <filter> <domain-name>example.com</domain-name> </filter> </delete> </protected_dir> </packet>

The packet that removes all protected directories available for packet sender looks as follows:
<packet version="1.5.2.0"> <protected_dir> <delete> <filter/> </delete> </protected_dir> </packet>

940

Supported Operations

Response Packet Structure


The delete node of the output XML packet is presented by type ProtectedDirDeleteOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is required if the operation succeeds. It returns the ID of the removed protected directory. Data type: integer.

Supported Operations

941

Response Samples
Removing a single protected directory The packet that removes the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <delete> <filter> <id>1</id> </filter> </delete> </protected_dir> </packet>

The positive response from the server looks as follows:


<protected_dir> <delete> <result> <status>ok</status> <filter-id>1</filter-id> <id>1</id> </result> </delete> </protected_dir>

If the protected directory was not found on the server, the response is as follows:
<protected_dir> <delete> <result> <status>error</status> <errcode>1013</errcode> <errtext>Protected URL is not found</errtext> <filter-id>1</filter-id> </result> ... </delete> </protected_dir>

Removing multiple protected directories The packet that removes all protected directories from domain with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <delete> <filter> <domain-id>1</domain-id> </filter> </delete> </protected_dir> </packet>

942

Supported Operations

A positive response from the server can look as follows:


<protected_dir> <delete> <result> <status>ok</status> <filter-id>1</filter-id> <id>74</id> </result> <result> <status>ok</status> <filter-id>1</filter-id> <id>78</id> </result> </delete> <result> <status>ok</status> <filter-id>1</filter-id> <id>79</id> </result> </delete> </protected_dir>

Retrieving Protected Directory Properties


Use the get operation to retrieve properties of a specific protected directory.

In this section:
Request Packet Structure.................................................................................. 942 Request Samples .............................................................................................. 943 Response Packet Structure ............................................................................... 944 Response Samples ........................................................................................... 945

Request Packet Structure


A request XML packet changing protected directory properties includes the get operation node:
<packet version="1.5.2.0"> <protected_dir> <get> ... </get> </protected_dir> </packet>

Supported Operations

943

The get node is presented by type ProtectedDirGetInput (protected_dir.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 923) section. Data type: ProtectedDirFilter (protected_dir.xsd).

Request Samples
Retrieving properties of a single protected directory The packet that retrieves properties of the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <filter> <id>1</id> </filter> </get> </protected_dir> </packet>

Retrieving properties of multiple protected directories The packet that retrieves properties of all protected directories of the domain with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <filter> <domain-id>1</domain-id> </filter> </get> </protected_dir> </packet>

The packet that retrieves properties of all protected directories of example.com domain looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <filter> <domain-name>example.com</domain-name> </filter> </get> </protected_dir> </packet>

944

Supported Operations

The packet that retrieves properties of all protected directories available for a packet sender looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <filter/> </get> </protected_dir> </packet>

Response Packet Structure


The get node of the output XML packet is presented by type ProtectedDirGetOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple.

Supported Operations

945

The id node is required if the operation succeeds. It returns the ID of the protected directory which properties were retrieved. Data type: integer. The data node is required if the operation succeeds. It specifies the protected directory properties. The node is presented by type: complex. Its graphical representation is as follows:

The name node is optional. It specifies the protected directory name. Data type: string. The header node is optional. It specifies the protected directory header. It is the message that is displayed to a user when he tries to access the protected directory. Data type: string. The location node is optional. It specifies protected directory properties. The node is present in the response packet only for Plesk for Linux/Unix servers. Data type: complex. The property node is required if the location node is specified. It specifies the protected directory property. Data type: ProtectedDirLocationProperty (protected_dir.xsd). The name node is required if the location node is specified. It specifies the protected directory property name. Data type: string. Names and values of properties that can be changed for a specific domain or common for all domains properties can be retrieved using the get-pd-location-descriptor operation. The value node is required if the location node is specified. It specifies the protected directory property value. Data type: boolean.

946

Supported Operations

Response Samples
Retrieving properties of a single protected directory The packet that retrieves properties of the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <filter> <id>1</id> </filter> </get> </protected_dir> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get> <result> <status>ok</status> <filter-id>1</filter-id> <id>1</id> <data> <name>directory</name> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>non-ssl</name> <value>true</value> </property> <property> <name>cgi</name> <value>true</value> </property> </location> </data> </result> </get> </protected_dir> </packet>

Supported Operations

947

If the protected directory was not found, the response from the server looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Protected URL is not found</errtext> <filter-id>1</filter-id> </result> </get> </protected_dir> </packet>

Retrieving properties of multiple protected directories The packet that retrieves properties of all protected directories of the domain with ID 132 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get> <filter> <domain-id>132</domain-id> </filter> </get> </protected_dir> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get> <result> <status>ok</status> <filter-id>132</filter-id> <id>34</id> <data> <name>directory</name> <header>This is a header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>non-ssl</name> <value>false</value> </property> <property> <name>cgi</name> <value>true</value> </property> </location> </data> </result> <result>

948

Supported Operations <status>ok</status> <filter-id>132</filter-id> <id>37</id> <data> <name>MySecondDirectory</name> <header>This is a the second directory header!</header> <location> <property> <name>ssl</name> <value>true</value> </property> <property> <name>non-ssl</name> <value>true</value> </property> <property> <name>cgi</name> <value>true</value> </property> </location> </data> </result> </get> </protected_dir> </packet>

Creating Protected Directory User


Use the add-user operation to create a protected directory user.

In this section:
Request Packet Structure.................................................................................. 948 Request Samples .............................................................................................. 949 Response Packet Structure ............................................................................... 949 Response Samples ........................................................................................... 951

Request Packet Structure


A request XML packet adding a protected directory user includes the add-user operation node:
<packet version="1.5.2.0"> <protected_dir> <add-user> ... </add-user> </protected_dir> </packet>

Supported Operations

949

The add-user node is presented by type ProtectedDirAddUserlInput (protected_dir.xsd), and its graphical representation is as follows:

The pd-id node is required. It specifies the protected directory ID. Data type: integer. The login node is required. It specifies the protected directory user login. Data type: string. The password node is required. It specifies the protected directory user password. Data type: string. The password-type node is optional. It specifies the protected directory user password type. Data type: string. Allowed values: plain | crypt.

Request Samples
The packet that creates user MyUser for the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <add-user> <pd-id>1</pd-id> <login>MyUser</login> <password>12345</password> <password-type>plain</password-type> </add-user> </protected_dir> </packet>

950

Supported Operations

Response Packet Structure


The add-user node of the output XML packet is presented by type ProtectedDirAddUserOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).

The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

The errcode node is optional. Is returns the error code if the operation fails. Data type: integer.

The errtext node is optional. It returns the error message if the operation fails. Data type: string.

The id node is required if the operation succeeds. It returns the ID of the added protected directory user. Data type: integer.

Supported Operations

951

Response Samples
The packet that creates user MyUser for the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <add-user> <pd-id>1</pd-id> <login>MyUser</login> <password>12345</password> <password-type>plain</password-type> </add-user> </protected_dir> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <protected_dir> <add-user> <result> <status>ok</status> <id>1</id> </result> </add-user> </protected_dir> </packet>

If the user already exists, the response from the server looks as follows:
<packet version="1.5.2.0"> <protected_dir> <add-user> <result> <status>error</status> <errcode>1007</errcode> <errtext>Specified user is already exist</errtext> </result> </add-user> </protected_dir> </packet>

952

Supported Operations

Changing Protected Directory User Settings


Use the set-user operation to change settings of the protected directory user.

In this section:
Request Packet Structure.................................................................................. 952 Request Samples .............................................................................................. 953 Response Packet Structure ............................................................................... 954 Response Samples ........................................................................................... 955

Request Packet Structure


A request XML packet changing protected directory user settings includes the set-user operation node:
<packet version="1.5.2.0"> <protected_dir> <set-user> ... </set-user> </protected_dir> </packet>

The set-user node is presented by type ProtectedDirSetInput (protected_dir.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 923) section. Data type: ProtectedDirUserFilter (protected_dir.xsd). The values node is required. It specifies the protected directory name. The node is presented by type ProtectedDirUser (protected_dir.xsd). Its graphical representation is as follows:

Supported Operations

953

The login node is optional. It specifies the protected directory user login. Data type: string. The password node is optional. It specifies the protected directory user password. Data type: string. The password-type node is optional. It specifies the protected directory user password type. Data type: string. Allowed values: plain | crypt.

Request Samples
Changing settings of a single protected directory user The packet that changes settings of a protected directory user with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <filter> <id>1</id> </filter> <values> <password>qweqwe</password> <password-type>plain</password-type> </values> </set-user> </protected_dir> </packet>

Changing settings of multiple protected directory users The packet that changes settings of all users of the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <filter> <pd-id>1</pd-id> </filter> <values> <password>qweqwe</password> <password-type>plain</password-type> </values> </set-user> </protected_dir> </packet>

The packet that changes settings of users of all protected directories available for a packet sender looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <filter/> <values> <password>qweqwe</password> <password-type>plain</password-type> </values> </set-user></protected_dir></packet>

954

Supported Operations

Response Packet Structure


The set-user node of the output XML packet is presented by type ProtectedDirSetUserOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is required if the operation succeeds. It returns the ID of the protected directory user whose settings were changed. Data type: integer.

Supported Operations

955

Response Samples
Changing preferences of a single protected directory user The packet that changes preferences of a protected directory user with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <filter> <id>1</id> </filter> <values> <password>qweqwe</password> <password-type>plain</password-type> </values> </set-user> </protected_dir> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <protected_dir> <set-user> <result> <status>ok</status> <filter-id>1</filter-id> <id>1</id> </result> </set-user> </protected_dir> </packet>

If the user was not found, the response from the server looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <result> <status>error</status> <errcode>1013</errcode> <errtext>User is not found</errtext> <filter-id>12</filter-id> </result> </set-user> </protected_dir> </packet>

956

Supported Operations

If no password was specified in the request packet, the response from the server looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <result> <status>error</status> <errcode>1019</errcode> <errtext>Invalid value for 'password' specified</errtext> <filter-id>12</filter-id> </result> </set-user> </protected_dir> </packet>

Changing preferences of multiple protected directory users The packet that changes preferences of all users of the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <set-user> <filter> <pd-id>1</pd-id> </filter> <values> <password>qweqwe</password> <password-type>plain</password-type> </values> </set-user> </protected_dir> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <set-user> <result> <status>ok</status> <filter-id>1</filter-id> <id>13</id> </result> <result> <status>ok</status> <filter-id>1</filter-id> <id>14</id> </result> </set-user> </protected_dir> </packet>

Supported Operations

957

Removing Protected Directory User


Use the delete-user operation to remove a protected directory user.

In this section:
Request Packet Structure.................................................................................. 957 Request Samples .............................................................................................. 957 Response Packet Structure ............................................................................... 958 Response Samples ........................................................................................... 959

Request Packet Structure


A request XML packet removing a protected directory user includes the delete-user operation node:
<packet version="1.5.2.0"> <protected_dir> <delete-user> ... </delete-user> </protected_dir> </packet>

The delete-user node is presented by type ProtectedDirDeleteUserInput (protected_dir.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 924) section. Data type: ProtectedDirUserFilter (protected_dir.xsd).

Request Samples
Removing a single protected directory user The packet that removes the protected user with ID 12 is as follows:
<packet version="1.5.2.0"> <protected_dir> <delete-user> <filter> <id>12</id> </filter> </delete-user> </protected_dir> </packet>

958

Supported Operations

Removing multiple protected directory users The packet that removes all protected users of the directory with ID 12 is as follows:
<packet version="1.5.2.0"> <protected_dir> <delete-user> <filter> <pd-id>12</pd-id> </filter> </delete-user> </protected_dir> </packet>

The packet that removes all protected users that are managed by a packet sender as follows:
<packet version="1.5.2.0"> <protected_dir> <delete-user> <filter/> </delete-user> </protected_dir> </packet>

Response Packet Structure


The delete-user node of the output XML packet is presented by type ProtectedDirDeleteUserOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

Supported Operations

959

The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is required if the operation succeeds. It returns the ID of the removed protected directory user. Data type: integer.

Response Samples
Removing a single protected directory user The packet that removes the protected user with ID 12 is as follows:
<packet version="1.5.2.0"> <protected_dir> <delete-user> <filter> <id>12</id> </filter> </delete-user> </protected_dir> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <protected_dir> <delete-user> <result> <status>ok</status> <filter-id>12</filter-id> <id>12</id> </result> </delete-user> </protected_dir> </packet>

If the user was not found, the response from the server looks as follows:
<protected_dir> <delete-user> <result> <status>error</status> <errcode>1013</errcode> <errtext>User is not found</errtext> <filter-id>12</filter-id> </result> </delete-user> </protected_dir>

960

Supported Operations

Removing multiple protected directory users The packet that removes all protected users of the directory with ID 12 is as follows:
<packet version="1.5.2.0"> <protected_dir> <delete-user> <filter> <pd-id>12</pd-id> </filter> </delete-user> </protected_dir> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <delete-user> <result> <status>ok</status> <filter-id>12</filter-id> <id>1</id> </result> <result> <status>ok</status> <filter-id>12</filter-id> <id>2</id> </result> </delete-user> </protected_dir> </packet>

Supported Operations

961

Retrieving Protected Directory User Settings


Use the get-user operation to retrieve protected directory user settings.

In this section:
Request Packet Structure.................................................................................. 961 Request Samples .............................................................................................. 962 Response Packet Structure ............................................................................... 963 Response Samples ........................................................................................... 964

Request Packet Structure


A request XML packet retrieving protected directory user settings includes the get-user operation node:
<packet version="1.5.2.0"> <protected_dir> <get-user> ... </get-user> </protected_dir> </packet>

The get-user node is presented by type ProtectedDirGetUserInput (protected_dir.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 924) section. Data type: ProtectedDirUserFilter (protected_dir.xsd).

962

Supported Operations

Request Samples
Retrieving settings of a single protected directory user The packet that retrieves settings of the protected directory user with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-user> <filter> <id>1</id> </filter> </get-user> </protected_dir> </packet>

Retrieving settings of multiple protected directory users The packet that retrieves settings of all users of the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-user> <filter> <pd-id>1</pd-id> </filter> </get-user> </protected_dir> </packet>

The packet that retrieves settings of all users that are managed by a packet sender looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-user> <filter/> </get-user> </protected_dir> </packet>

Supported Operations

963

Response Packet Structure


The delete-user node of the output XML packet is presented by type ProtectedDirGetUserOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is required if the operation succeeds. It returns the ID of the protected directory user. Data type: integer. The data node is required if the operation succeeds. It contains protected user settings. Data type: complex. The login node is required if the operation succeeds. It contains the protected user login. Data type: string.

964

Supported Operations

Response Samples
Retrieving settings of a single protected directory user The packet that retrieves settings of the protected directory user with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-user> <filter> <id>1</id> </filter> </get-user> </protected_dir> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get-user> <result> <status>ok</status> <filter-id>1</filter-id> <id>1</id> <data> <login>user</login> </data> </result> </get-user> </protected_dir> </packet>

If the user was not found, the response from the server looks as follows:
<protected_dir> <get-user> <result> <status>error</status> <errcode>1013</errcode> <errtext>User is not found</errtext> <filter-id>1</filter-id> </result> </get-user> </protected_dir>

Retrieving settings of multiple protected directory users The packet that retrieves settings of all users of the protected directory with ID 1 looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-user> <filter> <pd-id>1</pd-id> </filter> </get-user> </protected_dir> </packet>

Supported Operations

965

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get-user> <result> <status>ok</status> <filter-id>1</filter-id> <id>131</id> <data> <login>GuestUser</login> </data> </result> <result> <status>ok</status> <filter-id>1</filter-id> <id>132</id> <data> <login>MyUser</login> </data> </result> </get-user> </protected_dir> </packet>

Retrieving Descriptor of Protected Directory Properties


Use the get-pd-location-descriptor operation to retrieve descriptor of protected directory properties. For details on descriptors, refer to the Representation of Object Descriptor (on page 47) section of the API RPC Reference and the Descriptors Overview Section of the API RPC Developer's Guide.

In this section:
Request Packet Structure.................................................................................. 965 Request Samples .............................................................................................. 966 Response Packet Structure ............................................................................... 967 Response Samples ........................................................................................... 968

Request Packet Structure


A request XML packet retrieving protected directory descriptors includes the get-pdlocation-descriptor operation node:
<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> ... </get-pd-location-descriptor> </protected_dir> </packet>

966

Supported Operations

The get-pd-location-descriptor node is presented by type ProtectedDirGetLocationDescriptor (protected_dir.xsd), and its graphical representation is as follows:

The filter node is required. All protected directories on a domain share the same properties descriptor. To retrieve properties descriptor of all protected directories of a specific domain (domain-level descriptor), specify node domain-id in the filtering rule. You can specify multiple domain-id nodes to retrieve the properties descriptors for multiple domains. Use blank filter (<filter/>) to retrieve descriptor of common protected directory properties (server-level descriptor). . Data type: complex. The domain-id node is optional. It specifies the ID of the domain containing protected directories. Data type: integer.

Request Samples
The packet that requests for server-level properties descriptor looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <filter/> </get-pd-location-descriptor> </protected_dir> </packet>

The packet that requests for domain-level properties descriptor looks as follows::
<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <filter> <domain-id>1</domain-id> </filter> </get-pd-location-descriptor> </protected_dir> </packet>

Supported Operations

967

Response Packet Structure


The delete-user node of the output XML packet is presented by type ProtectedDirDeleteUserOutput (protected_dir.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is required if the request packet is valid. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is optional. This node is not presented in the response packet of the operation. The descriptor node is required only in Plesk for Linux/Unix if the operation succeeds. It contains the properties descriptor. Data type: complex. For details, refer to the Representation of Object Descriptor (on page 47) section. In Plesk for Windows the node is not presented in the response packet.

968

Supported Operations

Response Samples
Retrieving server-level descriptor The packet that requests for server-level properties descriptor looks as follows:
<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <filter/> </get-pd-location-descriptor> </protected_dir> </packet>

In Plesk for Linux/Unix, the server response can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <result> <status>ok</status> <descriptor> <property> <name>ssl</name> <type>boolean</type> <default>true</default> </property> <property> <name>nonssl</name> <type>boolean</type> <default>true</default> </property> <property> <name>cgi</name> <type>boolean</type> <default>false</default> </property> </descriptor> </result> </get-pd-location-descriptor> </protected_dir> </packet>

In Plesk for Windows, the server response can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <result> <status>ok</status> </result> </get-pd-location-descriptor> </protected_dir> </packet>

Supported Operations

969

Retrieving domain-level descriptor The packet that requests for domain-level properties descriptor looks as follows::
<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <filter> <domain-id>100</domain-id> </filter> </get-pd-location-descriptor> </protected_dir> </packet>

In Plesk for Linux/Unix, the server response can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <result> <status>ok</status> <filter-id>100</filter-id> <descriptor> <property> <name>ssl</name> <type>boolean</type> <default>true</default> <writable-by>admin</writable-by> <writable-by>client</writable-by> <writable-by>domain-admin</writable-by> </property> <property> <name>nonssl</name> <type>boolean</type> <default>true</default> <writable-by>admin</writable-by> <writable-by>client</writable-by> <writable-by>domain-admin</writable-by> </property> <property> <name>cgi</name> <type>boolean</type> <default>false</default> <writable-by>admin</writable-by> <writable-by>client</writable-by> <writable-by>domain-admin</writable-by> </property> </descriptor> </result> </get-pd-location-descriptor> </protected_dir> </packet>

970

Supported Operations

In Plesk for Windows, the server response can look as follows:


<packet version="1.5.2.0"> <protected_dir> <get-pd-location-descriptor> <result> <status>ok</status> <filter-id>100</filter-id> </result> </get-pd-location-descriptor> </protected_dir> </packet>

Managing Reseller Accounts


Operator: <reseller> XML Schema: reseller.xsd Plesk version: Plesk 9.0 for Windows and later | Plesk 9.0 for Linux/Unix and later API RPC version: 1.6.0.0 Plesk user: Plesk Administrator, Plesk reseller (since protocol version 1.6.0.0) Description Plesk resellers are Plesk users who own and manage Plesk client and Plesk domains accounts. All reseller accounts are managed by Plesk Administrator. Reseller account presents a set of reseller personal data and a collection of various settings. These settings are as follows: limits on Plesk resources usage, and limits usage policy permissions IP pool settings application pool settings

Once created, a reseller account is allotted a portion of Plesk server resources. A reseller account can be created with a unique collection of settings, or this can be done using a reseller template (Plesk object that holds a collection of predefined settings). To learn more about reseller templates, refer to the Managing Reseller Templates section.

In this section:
Reseller Settings ............................................................................................... 972 Filtering Issues .................................................................................................. 980 Creating Reseller Accounts ............................................................................... 982 Setting Reseller Account Properties .................................................................. 987 Retrieving Information on Reseller Accounts ..................................................... 992 Removing Reseller Accounts ............................................................................ 999 Adding IP Addresses to Reseller's IP Pool ........................................................ 1002

Supported Operations

971

Removing IP Addresses from Reseller's IP Pool ............................................... 1006 Changing IP Address Type in Reseller's IP Pool ............................................... 1009 Changing Types of Application Packages in Reseller's Application Pool ........... 1012 Viewing Buttons Displayed on Reseller's Home Page in Control Panel ............ 1016 Retrieving Descriptor of Limits ........................................................................... 1021 Retrieving Descriptor of Permissions ................................................................. 1024 Downgrading Reseller Account to Client Account .............................................. 1027

Supported Operations

ADD (on page 982) creates a reseller account SET (on page 987) modifies reseller account settings GET (on page 992) retrieves information on reseller accounts DEL (on page 999) removes reseller accounts

972

Supported Operations

IPPOOL-ADD-IP (on page 1002) adds IP addresses to a reseller's IP pool IPPOOL-DEL-IP (on page 1006) removes IP addresses from a reseller's IP pool IPPOOL-SET-IP (on page 1009) changes type of IP addresses (shared/exclusive) in a reseller's IP pool APP-POOL-SET-PKG (on page 1012) changes type of application packages (free/commercial) located in a reseller's application pool CFORM-BUTTONS-LIST (on page 1016) displays a buttons list for a reseller's home page GET-LIMIT-DESCRIPTOR (on page 1021) retrieves reseller limit descriptor GET-PERMISSION-DESCRIPTOR (on page 1024) retrieves reseller permission descriptor RESELLER-TO-CLIENT (on page 1027) downgrades reseller accounts to client accounts

Reseller Settings
This section describes a collection of reseller account settings. These settings can be defined when creating a reseller account or later, and retrieved from Plesk database as well.

In this section:
General Reseller Account Settings .................................................................... 972 Limits................................................................................................................. 978 Permissions....................................................................................................... 979

General Reseller Account Settings


General reseller account settings are specified by the following types: type ResellerAddGenInfo (on page 972) - used when creating a reseller account with the add operation type ResellerSetGenInfo (on page 974) - used when updating a reseller account with the set operation type ResellerGetGenInfo (on page 977) - used when retrieving the general information on a reseller account from Plesk database with the get operation

In this section:
Type ResellerAddGenInfo ................................................................................. 972 Type ResellerSetGenInfo .................................................................................. 974 Type ResellerGetGenInfo .................................................................................. 977

Supported Operations

973

Type ResellerAddGenInfo
When creating a reseller account, the general reseller account information is specified by the complex type ResellerAddGenInfo (reseller.xsd). It is structured as follows:

The cname node is optional. It specifies reseller company name. Data type: string. The pname node is required. It specifies personal reseller name. Data type: string. The login node is required. It specifies login name of a reseller account. Data type: string. The passwd node is required. It specifies password of a reseller account. Data type: string.

974

Supported Operations

The status node is optional. It specifies current status of a reseller account. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled_by admin) | 4 (under backup/restore) | 256 (expired). Note: Only status values 0 and 16 can be set up.

The phone node is optional. It specifies reseller phone number. Data type: string. The fax node is optional. It specifies reseller fax number. Data type: string. The email node is optional. It specifies reseller email address. Data type: string. The address node is optional. It specifies reseller postal address. Data type: string. The city node is optional. It specifies reseller city. Data type: string. The state node is optional. It specifies reseller US state (for US citizens only). Data type: string. The pcode node is optional. It specifies reseller zip code (for US citizens only). Data type: string. The country node is optional. It specifies 2-character code of a reseller country (US for United States, CA for Canada, etc.). Data type: string. The locale node is optional. It specifies locale used in Plesk GUI for the reseller account. The locale code must be in the format <languagecode2><country/regioncode2>. Data type: string. Default value: en-US.

Supported Operations

975

Type ResellerSetGenInfo
When setting the general reseller account information, the complex type ResellerSetGenInfo (reseller.xsd) is used in the request set packet. It is structured as follows:

The cname node is optional. It specifies reseller company name. Data type: string. The pname node is optional. It specifies reseller personal name. Data type: string. The login node is optional. It specifies reseller login name. Data type: string. The passwd node is optional. It specifies reseller account password. Data type: string. The status node is optional. It specifies current status of a reseller account. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled_by admin) | 4 (under backup/restore) | 256 (expired). Default value: 0. Note: Only status values 0 and 16 can be set up.

976

Supported Operations

The phone node is optional. It specifies reseller phone number. Data type: string. The fax node is optional. It specifies reseller fax number. Data type: string. The email node is optional. It specifies reseller email address. Data type: string. The address node is optional. It specifies reseller postal address. Data type: string. The city node is optional. It specifies reseller city. Data type: string. The state node is optional. It specifies reseller US state (for US citizens only). Data type: string. The pcode node is optional. It specifies a reseller zip code (for US citizens only). Data type: string. The country node is optional. It specifies 2-character code of a reseller country (US for United States, CA for Canada, etc.). Data type: string (2 characters long). The locale node is optional. It specifies code of a locale used in Plesk GUI for the reseller account. The locale code must be in the format <languagecode2><country/regioncode2> (RFC 1766 standard). Data type: string. Default value: enUS. The guid node is optional. If specified, a new GUID is assigned to a reseller account. For details on GUIDs, refer to the GUIDs Overview section of the API RPC Developer Guide. Data type: none.

Supported Operations

977

Type ResellerGetGenInfo
When getting the general reseller account information, the complex type ResellerGetGenInfo (reseller.xsd) is used in the response get packet. It is structured as follows:

The cr-date node is required. It specifies date when a reseller account was created. Data type: date. The cname node is required. It specifies reseller company name. Data type: string. The pname node is required. It specifies reseller personal name. Data type: string. The login node is required. It specifies login name of a reseller account. Data type: string.

978

Supported Operations

The status node is required. It specifies current status of a reseller account. Data type: objectStatus (plesk_common.xsd). Allowed values: 0 (active) | 16 (disabled_by admin) | 4 (under backup/restore) | 256 (expired). Default value: 0. The phone node is required. It specifies reseller phone number. Data type: string. The fax node is required. It specifies reseller fax number. Data type: string. The email node is required. It specifies reseller email address. Data type: string. The address node is required. It specifies reseller postal address. Data type: string. The city node is required. It specifies reseller city. Data type: string. The state node is required. It specifies reseller US state (for US citizens only). Data type: string. The pcode node is required. It specifies reseller zip code (for US citizens only). Data type: string. The country node is required. It specifies 2-character code of a reseller country (US for United States, CA for Canada, etc.). Data type: string. The locale node is required. It specifies code of a locale used for a reseller account. The locale code must be in the format <languagecode2>-<country/regioncode2> (RFC 1766 standard). Data type: string. Default value: en-US. The password node is optional. Specifies the client account password. Data type: string. Deprecated in API RPC v.1.4.2.0. The password_type node is optional. Specifies the type of the client account password. Data type: string. Allowed values: crypt | plain.The guid node is optional. It specifies a reseller account GUID. Data type: string. For details on GUIDs, refer to the GUIDs Overview section of the API RPC Developer's Guide.

Limits
Reseller limits policy, and limits on use Plesk resources are specified by the limits node. This node is presented by the ResellerLimits type (reseller.xsd), and its graphical representation is as follows:

The resource-policy node is required. It specifies limits policy for a reseller account. Data type: none. The oversell node is optional. It specifies whether the oversell policy is allowed for a reseller account. Data type: boolean.

Supported Operations

979

The overuse node is optional. It specifies the limits overuse policy for a reseller account. Data type: string. Allowed values: block | notify | normal.

The limit node is optional. It specifies limits on use Plesk resources for a reseller account. Data type: PleskLimitType (plesk_common.xsd). The name node is required. It specifies a limit name. Data type: sting. The value node is required. It specifies a limit value. Data type: anySimpleType.

Note: You can specify multiple limit parameters within one limits node. The following piece of code sets the limits overuse policy, and the maximum databases limit:
<limits> <resource-policy> <overuse>block/overuse> </resource-policy> <limit> <name>max_db</name> <value>100</value> </limit> </limits>

Note: To manage limits policy and limits on Plesk resources usage, you should first retrieve limits descriptor (for a specified reseller) containing names of limits. For details, refer to the Retrieving Descriptor of Limits (on page 119) section.

Permissions
Reseller permissions are specified by the permissions node which is presented by clientPerms type (plesk_client.xsd). The permissions node graphical representation is as follows:

The permission node is required. It specifies permission parameters. Data type: PleskPermissionType (plesk_common.xsd). The name node is required. It specifies permission name. Data type: sting. The value node is required. It specifies permission value. Data type: anySimpleType.

Note: You can specify multiple permission parameters within one permissions node.

980

Supported Operations

The following piece of code represents a permission on creating domains:


<permissions> <permission> <name>create_domains</name> <value>true</value> </permission> </permissions>

Note: To manage permissions, you should first retrieve permissions descriptor (for a specified reseller) which contains the permissions names. For details, refer to the Retrieving Descriptor of Permissions (on page 125) section.

Filtering Issues
Filtering is the way a request XML packet indicates the object (one or several reseller accounts) to which an operation is to be applied. Parameters nested in the filter node are called filtering rule. The filter node is presented by the ResellerSelectionFilter complex type (reseller.xsd). This data type is structured as follows:

The id node is optional. It specifies the reseller ID. Data type: id_type (common.xsd). The login node is optional. It specifies the reseller login. Data type: string. The guid node is optional. It specifies the reseller GUID. Data type: none. The all node is optional. It is used for applying an operation for all resellers. Data type: none.

Several resellers can be filtered either by their IDs or by their logins with one filter node, mixing the id and login nodes within the same filter node is prohibited.

Supported Operations

981

The following packet removes three reseller accounts specified by their id:
<packet version="1.6.0.0"> <reseller> <del> <filter> <id>24</id> <id>25</id> <id>27</id> </filter> </del> </reseller> </packet>

The following packet is identical except it specifies reseller accounts by name:


<packet version="1.6.0.0"> <reseller> <del> <filter> <login>JohnDoe</login> <login>JaneDoe</login> <login>RichardRoe</login> </filter> </del> </reseller> </packet>

The following packet removes all reseller accounts:


<packet version="1.6.0.0"> <reseller> <del> <filter> <all/> </filter> </del> </reseller> </packet>

The following packet is invalid as both the id node and the login node are used in the same filter:
<packet version="1.6.0.0"> <reseller> <del> <filter> <login>JohnDoe</login> <id>25</id> <login>RichardRoe</login> </filter> </del> </reseller> </packet>

982

Supported Operations

To fix this problem, use two different <del> sections:


<packet version="1.6.0.0"> <reseller> <del> <filter> <login>JohnDoe</login> <login>RichardRoe</login> </filter> </del> <del> <filter> <id>25</id> </filter> </del> </reseller> </packet>

Creating Reseller Accounts


The add operation is used to create reseller accounts. A reseller account presents personal information on a reseller and a collection of various settings. These settings are as follows: limits policy and limits on using Plesk resources permissions on using Plesk resources and managing own services application pool settings

The personal information is always specified when a reseller account is created, while the settings can be specified later. The only exception is a reseller template. It can be applied only when creating a reseller account. To learn more about reseller templates, refer to the Managing Reseller Templates section.

In this section:
Request Packet Structure.................................................................................. 983 Request Samples .............................................................................................. 984 Response Packet Structure ............................................................................... 986 Response Samples ........................................................................................... 987

Supported Operations

983

Request Packet Structure


A request XML packet adding a new reseller to Plesk, includes the add operation node:
<packet version="1.6.0.0"> <reseller> <add> </add> </reseller> </packet>

The add node is presented by the ResellerAddInput complex type (reseller.xsd). Its graphical representation is as follows:

The gen-info node is required. It specifies general information on a new reseller account. Data type: ResellerAddGenInfo (reseller.xsd). To view the structure of this node, refer to the Type ResellerAddGenInfo (on page 972) section. The add-packages-to-app-pool node is optional. It specifies Web application packages which are to be added to a reseller's application pool. Data type: ResellerAddPackagesToPool (reseller.xsd). View the structure of this node below. The limits node is optional. It specifies limits on using Plesk resources and limits policy for a new reseller. Data type: resellerLimits (reseller.xsd). To view structure of this node, refer to the Limits (on page 978) section. The permissions node is optional. It specifies reseller's permissions on using Plesk resources and managing own services. Data type: clientPerms (plesk_client.xsd). To view structure of this node, refer to the Permissions (on page 979) section. The template-id node is optional. It specifies reseller template ID in Plesk database. Data type: id_type (common.xsd). The template-name node is optional. It specifies reseller template name. Data type: string.

984

Supported Operations

The sbnet-user node is optional. It specifies whether Sitebuilder reseller account is to be created for a reseller account. Data type: boolean.

The add-packages-to-app-pool node is structured as follows:

The package-id node is required. It specifies ID of a Web application package which is to be added to a reseller's application pool. Data type: integer.

Request Samples
The following packet creates a reseller account:
<packet version="1.6.0.0"> <reseller> <add> <gen-info> <pname>John Doe</pname> <login>JDoe</login> <passwd>sample</passwd> </gen-info> </add> </reseller> </packet>

The following packet creates a reseller account using the base_template:


<packet version="1.6.0.0"> <reseller> <add> <gen-info> <cname>LogicSoft Ltd.</cname> <pname>John Doe</pname> <login>JDoe</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@example.com</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <country>CA</country> </gen-info> <template-name>base_template</template-name> </add> </reseller> </packet>

Supported Operations

985

To create multiple reseller accounts, use different add operations for each:
<packet version="1.6.0.0"> <reseller> <add> <gen-info> <cname>LogicSoft Ltd.</cname> <pname>John Doe</pname> <login>JDoe</login> <passwd>Jhtr66fBB</passwd> <status>0</status> <phone>416 907 9944</phone> <fax>928 752 3905</fax> <email>host@example.com</email> <address>105 Brisbane Road, Unit 2</address> <city>Toronto</city> <country>CA</country> </gen-info> </add> <add> <gen-info> <cname>TechnoSoft Ltd.</cname> <pname>Richard Roe</pname> <login>RRoe</login> <passwd>Jk8Dhh6fBB</passwd> <status>0</status> <phone>416 907 3366</phone> <fax>928 752 3377</fax> <email>james@example.com</email> <address>122 Greenroad Valley, Unit 1</address> <city>Toronto</city> <country>CA</country> </gen-info> <template-name>base_template</template-name> </add> </reseller> </packet>

986

Supported Operations

Response Packet Structure


The add node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the add operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the add operation fails. It returns the error message. Data type: string. The id node is required if the add operation succeeds. It returns ID of the created reseller account. Data type: id_type (common.xsd).

Operation-specific Errors 1024 - License limits are reached.

Supported Operations

987

Response Samples
A response packet received after the reseller account is created successfully looks as follows:
<packet version="1.6.0.0"> <reseller> <add> <result> <status>ok</status> <id>29</id> </result> </add> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <add> <result> <status>error</status> <errcode>1013</errcode> <errtext>Template does not exist</errtext> </result> </add> </reseller> </packet>

Setting Reseller Account Properties


The set operation is used to modify reseller accounts. This modifications can refer to any or all of the following settings: general reseller settings limits policy and limits on Plesk resources usage permissions on using Plesk resources and managing services Sitebuilder user account

In this section:
Request Packet Structure.................................................................................. 988 Request Samples .............................................................................................. 989 Response Packet Structure ............................................................................... 990 Response Samples ........................................................................................... 991

988

Supported Operations

Request Packet Structure


A request XML packet updating settings for a specified reseller account includes the set operation node:
<packet version="1.6.0.0"> <reseller> <set> </set> </reseller> </packet>

The set node is presented by the ResellerSetInput complex type (reseller.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information on filters, refer to the Filtering Issues (on page 980) section. Data type: ResellerSelectionFilter (reseller.xsd). The values node is required. It specifies categories of settings which are to be modified. The gen-info node is optional. It specifies general information on a reseller account. Data type: ResellerSetGenInfo (reseller.xsd). To view the structure of this node, refer to the Type ResellerSetGenInfo (on page 974) section. The limits node is optional. It specifies limits policy and limits on Plesk resources usage for a reseller. Data type: resellerLimits (reseller.xsd). To view the structure of this node, refer to the Limits (on page 978) section. The permissions node is optional. It specifies a set of reseller permissions. Data type: clientPerms (plesk_client.xsd). To view the structure of this node, refer to the Permissions (on page 979) section. The sbnet-user node is optional. It specifies whether a Sitebuilder user account is to be created for a reseller account. Data type: boolean.

Supported Operations

989

Request Samples
The following packet updates reseller accounts limits and sets the oversell limits policy for these accounts:
<packet version="1.6.0.0"> <reseller> <set> <filter> <login>JDoe</login> <login>RRoe</login> </filter> <values> <limits> <resource-policy> <oversell>true</oversell> </resource-policy> <limit> <name>disk_space</name> <value>209715200</value> </limit> <limit> <name>max_dom</name> <value>50</value> </limit> <limit> <name>max_subdom</name> <value>250</value> </limit> <limit> <name>max_webapps</name> <value>30</value> </limit> <limit> <name>max_traffic</name> <value>209715200</value> </limit> <limit> <name>max_db</name> <value>30</value> </limit> </limits> </values> </set> </reseller> </packet>

990

Supported Operations

The following packet sets the overuse limits policy for a reseller account:
<packet version="1.6.0.0"> <reseller> <set> <filter> <login>JDoe</login> </filter> <values> <limits> <resource-policy> <overuse>block</overuse> </resource-policy> </limits> </values> </set> </reseller> </packet>

Response Packet Structure


The set node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the set operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the set operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the set operation fails. It returns the error message. Data type: string. The filter-id node is required. It returns parameter by which the reseller account was filtered in the request packet. Data type: anySimple.

Supported Operations

991

The id node is required if the operation succeeds, or if the results are filtered by ID. It returns ID of the reseller which settings were modified. Data type: id_type (common.xsd).

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <set> <result> <status>ok</status> <filter-id>JDoe</filter-id> <id>2</id> </result> </set> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Reseller does not exist</errtext> <filter-id>RRoe</filter-id> <id>2</id> </result> </set> </reseller> </packet>

992

Supported Operations

Retrieving Information on Reseller Accounts


The get operation is used to retrieve information on reseller account settings from Plesk database. These settings are as follows: general information on a reseller (name, company, contact data, and so on) statistics limits policy and limits on Plesk resources usage permissions on using Plesk resources and managing services IP pool settings Sitebuilder account for a reseller account

In this section:
Request Packet Structure.................................................................................. 992 Request Samples .............................................................................................. 994 Response Packet Structure ............................................................................... 995 Response Samples ........................................................................................... 998

Request Packet Structure


A request XML packet retrieving information on reseller accounts from Plesk database includes the get operation node:
<packet version="1.6.0.0"> <reseller> <get> </get> </reseller> </packet>

Supported Operations

993

The get node is presented by the ResellerGetInput type (reseller.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: ResellerSelectionFilter. For more information on filters, refer to the Filtering Issues (on page 980) section. The dataset node is required. It specifies categories of settings requested from Plesk database. Data type: ResellerDataset (reseller.xsd). The gen-info node is optional. It is used to request general information on a reseller account. Data type: none. The stat node is optional. It is used to request reseller statistics. Data type: none. The permissions node is optional. It is used to request permissions set for a reseller account. Data type: none. The limits node is optional. It is used to request limits on Plesk resources, and limits policy set for a reseller account. Data type: none. The ippool node is optional. It is used to request IP pool settings for a reseller account. Data type: none.

994

Supported Operations

Request Samples
To retrieve information on reseller account, specify the packet as follows:
<packet version="1.6.0.0"> <reseller> <get> <filter> <id>1324</id> </filter> <dataset> <gen-info/> <stat/> <permissions/> <limits/> <ippool/> </dataset> </get> </reseller> </packet>

To send a similar packet for multiple reseller accounts, use the packet as follows:
<packet version="1.6.0.0"> <reseller> <get> <filter> <id>1324</id> <id>1325</id> </filter> <dataset> <gen-info/> <stat/> <permissions/> <limits/> <ippool/> </dataset> </get> </reseller> </packet>

Supported Operations

995

Response Packet Structure


The get node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the get operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the get operation fails. It returns the error message. Data type: string. The filter-id node is required. It returns parameter by which the reseller account was filtered in the request packet. Data type: anySimple. The id node is required if the operation succeeds, or if the results are filtered by ID. It returns ID of the reseller account which settings are retrieved in the response packet. Data type: integer. The data node is required if the get operation succeeds. It returns collection of requested reseller account settings. Data type: ResellerData (reseller.xsd). See the structure of this node below.

996

Supported Operations

The data node is structured as follows:

The gen-info node is optional. It returns general reseller account settings. Data type: resellerGetGenInfo (reseller.xsd). To view the structure of this node, refer to the Type ResellerGetGenInfo (on page 977) section. The stat node is optional. It returns statistics for a reseller account. Data type: ResellerStatType (reseller.xsd). View the structure of this node below. The permissions node is optional. It returns permissions set for a reseller account. Data type: clientPerms (plesk_client.xsd) . To view the structure of this node, refer to the Permissions (on page 979) section. The limits node is optional. It returns limits on Plesk resources usage and limits policy specified for a reseller account. Data type: ResellerLimits (reseller.xsd).To view the structure of this node, refer to the Limits (on page 978) section. The ippool node is optional. It returns IP pool settings for a reseller account. Data type: ipPoolType (plesk_client.xsd). The sbnet-user node is required if the operation succeeds. It indicates whether a Sitebuilder user account was created for a reseller account. Data type: boolean.

Supported Operations

997

The stat node is structured as follows:

The active-clients node is required. It specifies the number of active clients owned by a reseller. Data type: unsignedInt. Default value: 0. The active-domains node is required. It specifies the number of active domains owned by a reseller. Data type: unsignedInt. Default value: 0. The subdomains node is required. It specifies the number of subdomains created by a reseller. Data type: unsignedInt. Default value: 0. The domain-aliases node is required. It specifies the number of domain aliases created by a reseller. Data type: unsignedInt. Default value: 0. The disk-space node is required. It specifies the amount of disk space occupied by a reseller. Data type: integer. Default value: 0. The web-users node is required. It specifies the number of web users created by a reseller. Data type: unsignedInt. Default value: 0.

998

Supported Operations

The data-bases node is required. It specifies the number of databases used by a reseller. Data type: unsignedInt. Default value: 0. The postboxes node is required. It specifies the number of email boxes created by a reseller. Data type: unsignedInt. Default value: 0. The mbox-quota node is required. It specifies the amount of disk space that a single email box can occupy. Data type: unsignedInt. Default value: 0. The redirects node is required. It specifies the number of redirects created by a reseller. Data type: unsignedInt. Default value: 0. The mail-groups node is required. It specifies the number of email groups created by a reseller. Data type: unsignedInt. Default value: 0. The mail-resps node is required. It specifies the number of automatic response messages created by a reseller. Data type: unsignedInt. Default value: 0. The mail-lists node is required. It specifies the number of mailing lists created by a reseller. Data type: unsignedInt. Default value: 0. The webapps node is required. It specifies the number of Tomcat web applications used by a reseller. Data type: unsignedInt. Default value: 0. The traffic node is required. It specifies the amount of traffic (in bytes) spent by a reseller monthly. Data type: integer. Default value: 0. The traffic-prevday node is required. It specifies the amount of traffic (in bytes) spent by a reseller during the previous day. Data type: integer. Default value: 0.

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <get> <result> <status>ok</status> <filter-id>2</filter-id> <id>2</id> <data> <sbnet-user>false</sbnet-user> </data> </result> </get> </reseller> </packet>

Supported Operations

999

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <get> <result> <status>error</status> <errcode>1023</errcode> <errtext>admin is not a reseller</errtext> <filter-id>1</filter-id> <id>1</id> </result> </get> </reseller> </packet>

Removing Reseller Accounts


The del operation is used to remove reseller accounts and all their settings from Plesk database.

In this section:
Request Packet Structure.................................................................................. 999 Request Samples .............................................................................................. 1000 Response Packet Structure ............................................................................... 1001 Response Samples ........................................................................................... 1002

Request Packet Structure


A request XML packet removing a reseller account from Plesk database includes the del operation node:
<packet version="1.6.0.0"> <reseller> <del> </del> </reseller> </packet>

The del node is presented by the ResellerDelInput type (reseller.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: ResellerSelectionFilter. For more information on filters, refer to the Filtering Issues (on page 980) section.

1000

Supported Operations

Request Samples
To remove a reseller account, specify its ID or login name:
<packet version="1.6.0.0"> <reseller> <del> <filter> <id>1324</id> </filter> </del> </reseller> </packet>

To remove multiple reseller accounts, add either reseller IDs or login names to the filtering rule:
<packet version="1.6.0.0"> <reseller> <del> <filter> <id>1324</id> <id>1325</id> </filter> </del> </reseller> </packet>

To remove all reseller accounts, use the following packet:


<packet version="1.6.0.0"> <reseller> <del> <filter> <all/> </filter> </del> </reseller> </packet>

Supported Operations

1001

Response Packet Structure


The del node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the del operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the del operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the del operation fails. It returns the error message. Data type: string. The filter-id node is required. It returns the parameter by which the reseller account was filtered in the request packet. Data type: anySimple. The id node is required if the operation succeeds, or if the results are filtered by ID. It returns ID of the removed reseller account. Data type: id_type (common.xsd).

1002

Supported Operations

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <del> <result> <status>ok</status> <filter-id>2</filter-id> <id>2</id> </result> </del> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>Reseller does not exist</errtext> <filter-id>JDoe</filter-id> </result> </del> </reseller> </packet>

Supported Operations

1003

Adding IP Addresses to Reseller's IP Pool


The ippool-add-ip operation is used to add IP addresses to IP pool of a specified reseller account.

In this section:
Request Packet Structure.................................................................................. 1003 Request Samples .............................................................................................. 1004 Response Packet Structure ............................................................................... 1005 Response Samples ........................................................................................... 1006

Request Packet Structure


A request XML packet adding a new IP address to a reseller's IP pool includes the ippool-add-ip node:
<packet version="1.6.0.0"> <reseller> <ippool-add-ip> </ippool-add-ip> </reseller> </packet>

The ippool-add-ip node is specified by the ResellerIpPoolOperation complex type (reseller.xsd). Its graphical representation is as follows:

The reseller-id node is required. It specifies ID of a reseller account to which IP pool IP address is to be added. Data type: id_type (common.xsd). The ip node is required. It specifies settings of IP address which is to be added to a reseller's IP pool. The ip-address node is required. It specifies IP address which is to be added to a reseller's IP pool. Data type: ip_address (common.xsd). The ip-type node is optional. It specifies IP address type (shared or exclusive). Data type: ipType (plesk_common.xsd).

1004

Supported Operations

Request Samples
To add the 192.0.2.122 IP address to a resellers IP pool, use the following packet:
<packet version="1.6.0.0"> <reseller> <ippool-add-ip> <reseller-id>12</reseller-id> <ip> <ip-address>192.0.2.122</ip-address> </ip> </ippool-add-ip> </reseller> </packet>

Supported Operations

1005

Response Packet Structure


The ippool-add-ip node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the operation fails. It returns the error message. Data type: string. The ip-address node is required if the operation succeeds. It returns the IP address added to the reseller's IP pool. Data type: ip_address (common.xsd). The reseller-id node is optional. It returns the ID of the reseller account to IP pool of which the IP address was added. Data type: integer.

Possible Errors 1018 - IP address does not exist.

1006

Supported Operations

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <ippool-add-ip> <result> <status>ok</status> <ip-address>192.0.2.122</ip-address> </result> </ippool-add-ip> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <ippool-add-ip> <result> <status>error</status> <errcode>1023</errcode> <errtext>There is no IP address in the pool.</errtext> <ip-address>192.0.2.123</ip-address> </result> </ippool-add-ip> </reseller> </packet>

Supported Operations

1007

Removing IP Addresses from Reseller's IP Pool


The ippool-del-ip operation is used to remove IP addresses from the reseller's IP pool.

In this section:
Request Packet Structure.................................................................................. 1007 Request Samples .............................................................................................. 1008 Response Packet Structure ............................................................................... 1008 Response Samples ........................................................................................... 1009

Request Packet Structure


A request XML packet removing IP addresses from reseller's IP pool includes the ippool-del-ip node:
<packet version="1.6.0.0"> <reseller> <ippool-del-ip> </ippool-del-ip> </reseller> </packet>

The ippool-del-ip node is specified by ResellerIpPoolDelInput complex type (reseller.xsd). Its graphical representation is as follows:

The reseller-id node is required. It specifies the ID of a reseller account from whose IP pool an IP address is to be removed. Data type: integer. The ip-address node is required. It specifies an IP address which is to be removed from a reseller's IP pool. Data type: ip_address (common.xsd).

1008

Supported Operations

Request Samples
To remove IP addresses from a resellers IP pool, specify the packet as follows:
<packet version="1.6.0.0"> <reseller> <ippool-del-ip> <reseller-id>1234</reseller-id> <ip-address>192.0.2.122</ip-address> <ip-address>192.0.2.123</ip-address> </ippool-del-ip> </reseller> </packet>

Response Packet Structure


The ippool-del-ip node of the response packet is structured as follows (data type ResellerIpPoolOperationOutput (reseller.xsd)):

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the ippool-del-ip operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the ippool-del-ip operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the ippool-del-ip operation fails. It returns the error message. Data type: string.

Supported Operations

1009

The ip-address node is required if the operation succeeds. It returns the IP address added to the reseller's IP pool. Data type: ip_address (common.xsd). The reseller-id node is optional. It is not returned for this operation.

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <ippool-del-ip> <result> <status>ok</status> <ip-address>192.0.2.111</ip-address> </result> </ippool-del-ip> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <ippool-del-ip> <result> <status>error</status> <errcode>1023</errcode> <errtext>There is no IP address in the pool.</errtext> <ip-address>192.0.2.123</ip-address> </result> </ippool-del-ip> </reseller> </packet>

1010

Supported Operations

Changing IP Address Type in Reseller's IP Pool


The ippool-set-ip operation is used to change type of IP addresses located in a reseller's IP pool.

In this section:
Request Packet Structure.................................................................................. 1010 Request Samples .............................................................................................. 1011 Response Packet Structure ............................................................................... 1011 Response Samples ........................................................................................... 1012

Request Packet Structure


A request XML packet changing IP address type includes the ippool-set-ip node:
<packet version="1.6.0.0"> <reseller> <ippool-set-ip> </ippool-set-ip> </reseller> </packet>

The ippool-set-ip node is specified by the ipPoolResellerSet complex type (reseller.xsd). Its graphical representation is as follows:

The reseller-id node is required. It specifies ID of the reseller account which IP address is to be modified. Data type: id_type (common.xsd). The filter node is required. It specifies IP address which type is to be changed. If this node is empty, the operation will modify all IP addresses from the reseller's IP pool. Data type: none. The ip-address node is optional. It specifies IP addresses which types are to be modified. Data type: ip_address (common.xsd).

The values node is required. It specifies ip-address type which is to be set. Data type: none. The ip-type node is required.It specifies IP address type. Data type: ipType (plesk_common.xsd). Allowed values: shared | exclusive.

Supported Operations

1011

Request Samples
The following packet sets IP address type to shared:
<packet version="1.6.0.0"> <reseller> <ippool-set-ip> <reseller-id>10</reseller-id> <filter> <ip-address>192.0.2.40</ip-address> </filter> <values> <ip-type>shared</ip-type> </values> </reseller> </packet>

Response Packet Structure


The ippool-set-ip node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the operation fails. It returns the error message. Data type: string. The ip-address node is required if the operation succeeds. It returns the IP address added to the reseller's IP pool. Data type: ip_address (common.xsd).

1012

Supported Operations

The reseller-id node is optional. It is not returned for this operation.

Operation-specific Errors 1015 - reseller is not found 1013 - IP address is not found in reseller's IP pool

Response Samples

A positive response received from the server looks as follows:


<packet version="1.6.0.0"> <reseller> <ippool-set-ip> <result> <status>ok</status> <ip-address>127.0.0.1</ip-address> </result> </ippool-set-ip> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <ippool-set-ip> <result> <status>error</status> <errcode>1023</errcode> <errtext>Cannot modify IP address type</errtext> </result> </ippool-set-ip> </reseller> </packet>

Supported Operations

1013

Changing Types of Application Packages in Reseller's Application Pool


The app-pool-set-pkg operation is used to change type of application packages located in a reseller's application pool. The available types are free and commercial.

In this section:
Request Packet Structure.................................................................................. 1013 Request Samples .............................................................................................. 1014 Response Packet Structure ............................................................................... 1014 Response Samples ........................................................................................... 1015

Request Packet Structure


A request XML packet changing application package type includes the app-pool-set-pkg node:
<packet version="1.6.0.0"> <reseller> <app-pool-set-pkg> </app-pool-set-pkg> </reseller> </packet>

The app-pool-set-pkg node is specified by the AppPoolResellerSet complex type (reseller.xsd). Its graphical representation is as follows:

The reseller-id node is required. It specifies the ID of the reseller which application package is to be modified. Data type: integer. The filter node is required. It specifies the ID of a package which type is to be modified. The package-id node is optional. It specifies the ID of application package which type is to be changed. Data type: integer. The values node is required. It contains application package settings. The access-level node is optional. It specifies the application package type. Data type: string. Available values: free | commercial.

1014

Supported Operations

Request Samples
This packet modifies application package type:
<packet version="1.6.0.0"> <reseller> <app-pool-set-pkg> <reseller-id>3</reseller-id> <filter> <package-id>23</package-id> <package-id>25</package-id> </filter> <values> <access-level>commercial</access-level> </values> </app-pool-set-pkg> </reseller> </packet>

Response Packet Structure


The app-pool-set-pkg node of the response packet is structured as follows:

Supported Operations

1015

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the app-pool-setpkg operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the operation fails. It returns the error message. Data type: string. The package-id node is required if the operation succeeds. It returns ID of the application package which type was modified. Data type: integer. The reseller-id node is optional. It returns the ID of the reseller account. Data type: integer.

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <app-pool-set-pkg> <result> <status>ok</status> <package-id>1</package-id> </result> </app-pool-set-pkg> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <app-pool-set-pkg> <result> <status>error</status> <errcode>1013</errcode> <errtext>Item does not exist</errtext> </result> </app-pool-set-pkg> </reseller> </packet>

1016

Supported Operations

Viewing Buttons Displayed on Reseller's Home Page in Control Panel


The cform-buttons-list operation is used to retrieve a list of buttons displayed on a reseller's home page.

In this section:
Request Packet Structure.................................................................................. 1016 Request Samples .............................................................................................. 1016 Response Packet Structure ............................................................................... 1017 Response Samples ........................................................................................... 1020

Request Packet Structure


A request XML packet getting a list of buttons for a specified reseller account includes the cform-buttons-list operation node:
<packet version="1.6.0.0"> <reseller> <cform-buttons-list> </cform-buttons-list> </reseller> </packet>

The cform-buttons-list operation node has the following graphical representation:

The filter node is required. It specifies reseller accounts whose lists of buttons are to be displayed. Data type: ResellerSelectionFilter. To view the structure of this node, refer to the Filtering Issues (on page 980) section.

Request Samples
To view lists of buttons for all reseller accounts, specify the packet as follows:
<packet version="1.6.0.0"> <reseller> <cform-buttons-list> <filter> <all/> </filter> </cform-buttons-list> </reseller> </packet>

Supported Operations

1017

Response Packet Structure


A response cform-buttons-list packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the cform-buttonslist operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the cform-buttons-list operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the cform-buttons-list operation fails. It returns the error message. Data type: string. The filter-id node is required. It returns parameter by which the reseller account was filtered in the request packet. Data type: anySimple. The id node is required if the operation succeeds, or if the results are filtered by ID. It returns ID of the reseller account which list of buttons was returned. Data type: id_type (common.xsd). The button node is required if the cform-buttons-list operation succeeds. It returns information on each displayed reseller's button. Data type: buttonDataType (plesk_button.xsd). View the structure of this node below.

1018

Supported Operations

The button node is structured as follows:

The code node is required. It specifies button ID. Data type: string.

Supported Operations

1019

The type node is required. It specifies button type (a button pointing to a URL, or a button linked to a Web application). Data type: string. Allowed values: link_button | comm_button. The name node is required. It specifies localized button caption displayed in Plesk GUI. Data type: string. The name_id node is required. It specifies localization key of the button name. Data type: string. The group_name node is required. It specifies localized name of the section in which the button is located in Plesk GUI. Data type: string. The group_name_id node is required. It specifies localization key of the section name. Data type: string. The href node is required. It specifies URL referenced by a button. Data type: string. The js_onclick node is optional. It specifies JavaScript code executed at the button click. Data type: text. The enabled node is required. It specifies button status. Data type: boolean. The new_window node is optional. It indicates whether a new window is to be opened at the button click. Data type: boolean. The tabindex node is optional. It specifies tabulation index of the button. Data type: integer. Default value: 0. The conhelp_id node is optional. It specifies localization key of contextual help message associated with the button. Data type: string. The conhelp node is optional. It specifies contextual help message displayed for the button. Data type: text. The icon_url node is optional. It specifies URL of the buttons icon. Data type: string.

1020

Supported Operations

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <cform-buttons-list> <result> <status>ok</status> <filter-id>156</filter-id> <id>156</id> <button> <code>NEW_CLIENT_BUTTON</code> <type>link_button</type> <name>Create Client Account</name> <name_id>new_client</name_id> <group_name>Clients</group_name> <group_name_id>clients</group_name_id> <href>/plesk/reseller@/client@new/properties/?wizstep=1</href> <enabled>true</enabled> <new_window>false</new_window> <conhelp>Create a new client account</conhelp> <icon_url/> </button> <button> <code>CL_TMPL-ADD_BUTTON</code> <type>link_button</type> <name>Create Client Account Template</name> <name_id>cl_tmpl-add</name_id> <group_name>Clients</group_name> <group_name_id>clients</group_name_id> <href>/plesk/reseller@/clienttemplate@new/properties/?wizstep=1</href> <enabled>true</enabled> <new_window>false</new_window> <conhelp>Create a template for client accounts.</conhelp> <icon_url/> </button> </result> </cform-buttons-list> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <cform-buttons-list> <result> <status>error</status> <errcode>1013</errcode> <errtext>Reseller does not exist</errtext> <filter-id>JDoe</filter-id> </result> </cform-buttons-list> </reseller> </packet>

Supported Operations

1021

Retrieving Descriptor of Limits


The get-limit-descriptor operation is used to retrieve descriptor of a reseller's limits. For details on the limits descriptors, refer to the Representation of Object Descriptors (see page 47) section. For details on reseller's limits, refer to the Limits (on page 978) section.

In this section:
Request Packet Structure.................................................................................. 1021 Request Samples .............................................................................................. 1021 Response Packet Structure ............................................................................... 1022 Response Samples ........................................................................................... 1023

Request Packet Structure


A request XML packet retrieving reseller limits descriptor includes the get-limit-descriptor operation node:
<packet version="1.6.0.0"> <reseller> <get-limit-descriptor> </get-limit-descriptor> </reseller> </packet>

The get-limit-descriptor node has the following graphical representation:

The filter node is required. It specifies reseller accounts whose limit descriptors are to be retrieved. Data type: ResellerSelectionFilter. To view the structure of this node, refer to the Filtering Issues (on page 980) section.

1022

Supported Operations

Request Samples
The following packet retrieves limits descriptor for a reseller account:
<packet version="1.6.0.0"> <reseller> <get-limit-descriptor> <filter> <login>JDoe</login> </filter> </get-limit-descriptor> </reseller> </packet>

Response Packet Structure


A response get-limit-descriptor node is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-limitdescriptor operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the get-limit-descriptor operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the get-limit-descriptor operation fails. It returns the error message. Data type: string.

Supported Operations

1023

The filter-id node is required if the get-limit-descriptor operation succeeds. It returns parameter by which reseller account was filtered in the request packet. Data type: anySimple. The id node is required if the operation succeeds, or if the results are filtered by ID. It returns ID of the reseller account which limits descriptor was displayed. Data type: id_type (common.xsd). The descriptor node is required if the get-limit-descriptor operation succeeds. It specifies object descriptor. For details, refer to the Representation of Object Descriptors (see page 47) section. Data type: string. Note: This descriptor contains limits extensions. For details, refer to the Extension of Limits Descriptor (see page 53) section.

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <get-limit-descriptor> <result> <status>ok</status> <filter-id>180</filter-id> <id>180</id> <descriptor> <property> <name>max_dom</name> <type>int</type> <writable-by>admin</writable-by> <label>limit__max_dom</label> <extension> <shared>false</shared> </extension> </property> <property> ... </property> </descriptor> </result> </get-limit-descriptor> </reseller> </packet>

Note: Data structures that describe a number of properties are omitted to improve the readability of the sample.

1024

Supported Operations

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <get-limit-descriptor> <result> <status>error</status> <errcode>1013</errcode> <errtext>Reseller does not exist</errtext> <filter-id>JDoe</filter-id> </result> </get-limit-descriptor> </reseller> </packet>

Retrieving Descriptor of Permissions


The get-permission-descriptor operation is used to retrieve descriptor of reseller's permissions. For details on descriptor, refer to the Representation of Object Descriptors (see page 47) section. For details on reseller's permissions, refer to the Permissions (on page 979) section.

In this section:
Request Packet Structure.................................................................................. 1024 Request Samples .............................................................................................. 1025 Response Packet Structure ............................................................................... 1025 Response Samples ........................................................................................... 1026

Request Packet Structure


A request XML packet retrieving reseller permissions descriptor includes the getpermission-descriptor operation node:
<packet version="1.6.0.0"> <reseller> <get-permission-descriptor> </get-permission-descriptor> </reseller> </packet>

The get-permission-descriptor node has the following graphical representation:

The filter node is required. It specifies reseller accounts whose permissions descriptors are to be retrieved. Data type: ResellerSelectionFilter. To view the structure of this node, refer to the Filtering Issues (on page 980) section.

Supported Operations

1025

Request Samples
The following packet retrieves permissions descriptor for a reseller account:
<packet version="1.6.0.0"> <reseller> <get-permission-descriptor> <filter> <login>JDoe</login> </filter> </get-permission-descriptor> </reseller> </packet>

Response Packet Structure


A response get-permission-descriptor node is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the getpermission-descriptor operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the get-permission-descriptor operation fails. It returns the error code. Data type: unsignedInt.

1026

Supported Operations

The errtext node is required if the get-permission-descriptor operation fails. It returns the error message. Data type: string. The filter-id node is required if the get-permission-descriptor operation succeeds. It returns parameter by which reseller account was filtered in the request packet. Data type: anySimple. The id node is required if the get-permission-descriptor operation succeeds. It returns ID of the reseller account which permissions descriptor was displayed. Data type: id_type (common.xsd). The descriptor node is required if the get-permission-descriptor operation succeeds. It specifies object descriptor. For details, refer to the Representation of Object Descriptors (see page 47) section. Data type: string. Note: This descriptor contains permission extensions. For details, refer to the Extension of Permissions Descriptor (on page 51) section.

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <get-permission-descriptor> <result> <status>ok</status> <filter-id>180</filter-id> <id>180</id> <descriptor> <property> <name>create_clients</name> <type>boolean</type> <default-value>false</default-value> <writable-by>admin</writable-by> <label>cl_perm__create_clients</label> <extension> <level>client</level> </extension> </property> <property> ... </property> </descriptor> </result> </get-permission-descriptor> </reseller> </packet>

Note: Data structures that describe a number of properties are omitted to improve the readability of the sample.

Supported Operations

1027

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <get-permission-descriptor> <result> <status>error</status> <errcode>1013</errcode> <errtext>Reseller does not exist</errtext> <filter-id>JDoe</filter-id> </result> </get-permission-descriptor> </reseller> </packet>

Downgrading Reseller Account to Client Account


The convert-to-client operation is used to downgrade reseller account to client account. Downgrading to client account can be performed only if a reseller account owns no client accounts.

In this section:
Request Packet Structure.................................................................................. 1027 Request Samples .............................................................................................. 1028 Response Packet Structure ............................................................................... 1028 Response Samples ........................................................................................... 1029

Request Packet Structure


A request XML packet downgrading reseller account to client account includes the convert-to-client operation node:
<packet version="1.6.0.0"> <reseller> <convert-to-client> </convert-to-client> </reseller> </packet>

The convert-to-client operation node has the following graphics representation:

The filter node is required. It specifies reseller accounts that are to be converted to client accounts. Data type: ResellerSelectionFilter. To view the structure of this node, refer to the Filtering Issues (on page 980) section.

1028

Supported Operations

Request Samples
To convert reseller account to client account, specify the packet as follows:
<packet version="1.6.0.0"> <reseller> <convert-to-client> <filter> <login>JDoe</login> </filter> </convert-to-client> </reseller> </packet>

Response Packet Structure


A response convert-to-client packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the convert-toclient operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the convert-to-client operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the convert-to-client operation fails. It returns the error message. Data type: string. The filter-id node is required. It returns the parameter by which reseller account was filtered in the request packet. Data type: anySimple. The id node is required. It returns the ID of the reseller account which was converted to client account. Data type: id_type (common.xsd).

Supported Operations

1029

Response Samples
A positive response received from the server looks as follows:
<packet version="1.6.0.0"> <reseller> <convert-to-client> <result> <status>ok</status> <filter-id>JDoe</filter-id> <id>180</id> </result> </convert-to-client> </reseller> </packet>

A negative response received from the server can look as follows:


<packet version="1.6.0.0"> <reseller> <convert-to-client> <result> <status>error</status> <errcode>1019</errcode> <errtext>JDoe is not a reseller</errtext> <filter-id>JDoe</filter-id> <id>180</id> </result> </convert-to-client> </reseller> </packet>

1030

Supported Operations

Managing Reseller Templates


Operator: <reseller-template> XML Schema: reseller_template.xsd Plesk version: Plesk 9.0 for UNIX | Plesk 9.0 for Windows API RPC version: 1.6.0.0 Plesk user: Plesk Administrator Description Reseller templates are a kind of presets which are used for creating multiple reseller accounts with identical permissions, limits, IP pool settings, and preferences. All operations on reseller templates are available to Plesk Administrator only. Supported operations

ADD (on page 1035) creates a reseller template GET (on page 1039) retrieves information on reseller templates from Plesk database DEL (on page 1043) removes reseller templates SET (on page 1046) updates preferences, limits, permissions and IP pool settings for a reseller template

In this section:
Reseller Template Settings ............................................................................... 1031 Filtering Issues .................................................................................................. 1034 Creating Reseller Template ............................................................................... 1035 Retrieving Information About Reseller Templates .............................................. 1039 Removing Reseller Templates .......................................................................... 1043 Setting Reseller Template Properties ................................................................ 1046

Supported Operations

1031

Reseller Template Settings


This section describes a collection of reseller settings that can be specified in a reseller template. These settings can be defined when creating a reseller template or later, and retrieved from Plesk database as well.

In this section:
Limits................................................................................................................. 1031 Permissions....................................................................................................... 1032 IP Pool Settings................................................................................................. 1033 Preferences ....................................................................................................... 1034

Limits
Limits policy, and limits on use Plesk resources for resellers created with a reseller template are specified by the limits node. This node is presented by the ResellerLimits type (reseller.xsd), and its graphical representation is as follows:

The resource-policy node is optional. It specifies limits policy for reseller accounts created with a reseller template. Data type: none. The oversell node is optional. It specifies whether the limits oversell policy is allowed for reseller accounts created with the reseller template. Data type: boolean. The overuse node is optional. It specifies the limits overuse policy for reseller accounts created with the reseller template. Data type: string. Allowed values: block | notify | normal.

The limit node is optional. It specifies limits on Plesk resources usage for reseller accounts created with the reseller template. Data type: PleskLimitType (plesk_common.xsd). The name node is required. It specifies limit name. Data type: sting. The value node is required. It specifies limit value. Data type: anySimpleType.

Note: You can specify multiple limit parameters within one limits node.

1032

Supported Operations

The following code example sets the limits overuse policy, and the maximum databases limit:
<limits> <resource-policy> <overuse>block/overuse> </resource-policy> <limit> <name>max_db</name> <value>100</value> </limit> </limits>

Note: To manage limits policy and limits on Plesk resources usage for reseller templates, you should first retrieve limits descriptor containing names of limits. For details, refer to the Retrieving Descriptor of Limits (on page 119) section.

Permissions
Permissions for resellers created with a reseller template are specified by the permissions node which is presented by clientPerms type (plesk_client.xsd). The permissions node graphical representation is as follows:

The permission node is required. It specifies permission parameters. Data type: PleskPermissionType (plesk_common.xsd). The name node is required. It specifies permission name. Data type: sting. The value node is required. It specifies permission value. Data type: anySimpleType.

Note: You can specify multiple permission parameters within one permissions node. The following code represents the permission on creating domains:
<permissions> <permission> <name>create_domains</name> <value>true</value> </permission> </permissions>

Note: To set up permissions, you should first retrieve permissions descriptor, containing names of permissions. For details, refer to the Retrieving Descriptor of Permissions (on page 125) section.

Supported Operations

1033

IP Pool Settings
A reseller template can specify IP pool settings for resellers created with a reseller template. A reseller IP pool can contain a set of shared and exclusive IP addresses. A shared IP address is selected from Plesk server IP pool, and an exclusive IP address is created for a reseller. IP pool settings for resellers created with a reseller template are specified by the ip-pool node which is presented by the ResellerTemplateIpPoolType complex type (reseller-template.xsd). The ip-pool node is structured as follows:

The ip-address node is optional. It specifies IP address available in Plesk server IP pool that is to be shared by resellers created with a reseller template. Data type: ip_address (common.xsd). The allocate-ip node is optional. It specifies the maximum number of exclusive IP addresses from the server IP pool that can be used by a reseller. Data type: integer.

The following request packet creates a reseller template and sets IP pool settings for it:
<packet version="1.6.0.0"> <reseller-template> <add> <name>base_template</name> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> <allocate-ip>2</allocate-ip> </ip-pool> </add> </reseller-template> </packet>

1034

Supported Operations

Preferences
Preferences for resellers created with a reseller template are specified by the preferences node. This node is presented by the ResellerTemplatePreferencesType (reseller_template.xsd), and its graphical representation is as follows:

The sbnet-user node is optional. It indicates whether a reseller created with a reseller template will have a Sitebuilder reseller account. Data type: boolean.

The following request packet creates a reseller template and sets preferences for it:
<packet version="1.6.0.0"> <reseller-template> <add> <name>base_template</name> <preferences> <sbnet-user>true</sbnet_user> </preferences> </add> </reseller-template> </packet>

Filtering Issues
Filtering is the way a request XML packet indicates the object (one or several reseller templates) to which an operation is to be applied. Parameters nested in the filter node are called filtering rule. The filter node is presented by the ResellerTemplateFilterType complex type (reseller_template.xsd). This data type is structured as follows:

The id node is required. It specifies ID of a reseller template. Data type: integer.

Supported Operations

1035

The name node is required. It specifies name of a reseller template. Data type: string. The all node is required. It is used for applying an operation for all reseller templates. Data type: none.

A reseller template can be filtered by either the id node or the name node. The same is true if several reseller accounts are filtered by their IDs, or names with one filter node. Using different nodes within the same filter node is prohibited. To apply requested operation to all reseller templates, use the all node. For example, a packet that retrieves the information on all reseller accounts looks as follows:
<packet version="1.6.0.0"> <reseller-template> <get> <filter> <all/> </filter> </get> </reseller-template> </packet>

Note: The blank (<filter/>) filter node is deprecated.

Creating Reseller Template


The add operation is used to create reseller templates.

In this section:
Request Packet Structure.................................................................................. 1035 Request Samples .............................................................................................. 1036 Response Packet Structure ............................................................................... 1037 Response Samples ........................................................................................... 1038

Request Packet Structure


A request XML packet creating a reseller template includes the add operation node:
<packet version="1.6.0.0"> <reseller-template> <add> </add> </reseller-template> </packet>

1036

Supported Operations

The add node is presented by the ResellerTemplateAddInputType complex type (reseller_template.xsd). Its graphical representation is as follows:

The name node is required. It specifies reseller template name. Data type: string. The limits node is optional. It specifies limits policy and limits on Plesk resources usage that are to be set for resellers created with a reseller template. Data type: ResellerLimits (reseller.xsd). To view the structure of this node, refer to the Limits (on page 1031) section. The permissions node is optional. It specifies permissions for resellers created with a reseller template. Data type: clientPerms (plesk_client.xsd). To view the structure of this node, refer to the Permissions (on page 1032) section. The ip-pool node is optional. It specifies IP pool settings for resellers created with a reseller template. Data type: ResellerTemplateIpPoolType (reseller_template.xsd). To view the structure of this node, refer to the IP Pool Settings (on page 1033) section. The preferences node is optional. It specifies preferences for resellers created with a reseller template. Data type: ResellerTemplatePreferencesType (reseller_template.xsd). To view the structure of this node, refer to the Preferences (on page 1034) section.

Request Samples
The following packet creates a reseller template called sample_template and defines that resellers created with the template should automatically have in their IP pools two exclusive IP addresses:
<packet version="1.6.0.0"> <reseller-template> <add> <name>sample_template</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> </add> </reseller-template> </packet>

Supported Operations

1037

To create two reseller templates within a single packet, include two add operation nodes:
<packet version="1.6.0.0"> <reseller-template> <add> <name>sample_template</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> </add> <add> <name>base_template</name> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> </ip-pool> </add> </reseller-template> </packet>

Response Packet Structure


The add node of the response packet is structured as follows:

The result node is required. It wraps the response received from the server. Data type: ResellerTemplateOutputResulttype (reseller_template.xsd). The status node is required. It specifies the execution status of the add operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the add operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the add operation fails. It returns the error message. Data type: string.

1038

Supported Operations

The id node is required if the add operation succeeds. It returns ID of the created reseller template. Data type: integer. The name node is required if the add operation succeeds. It returns name of the created reseller template. Data type: string.

Response Samples
A positive response from the server can look as follows:
<packet version="1.6.0.0"> <reseller-template> <add> <result> <status>ok</status> <id>4</id> </result> </add> </reseller-template> </packet>

A negative response from the server can look as follows:


<packet version="1.6.0.0"> <reseller-template> <add> <result> <status>error</status> <errcode>1027</errcode> <errtext>Unable to set ip pool. The IPPool has wrong value</errtext> </result> </add> </reseller-template> </packet>

Supported Operations

1039

Retrieving Information About Reseller Templates


The get operation is used to retrieve information on reseller templates from Plesk database. This information is as follows: name and ID of a reseller template permissions limits policy and limits on using Plesk resources IP pool settings preferences

The get operation can return all or particular settings of a template. All settings are optional and can be missing in a reseller template.

In this section:
Request Packet Structure.................................................................................. 1039 Request Samples .............................................................................................. 1040 Response Packet Structure ............................................................................... 1041 Response Samples ........................................................................................... 1042

Request Packet Structure


A request XML packet retrieving information on specified reseller templates from Plesk database includes the get operation node:
<packet version="1.6.0.0"> <reseller-template> <get> </get> </reseller-template> </packet>

The get node is presented by type ResellerTemplateGetInputType (reseller_template.xsd). Its graphical representation is as follows:

1040

Supported Operations

The filter node is required. It specifies the filtering rule. For more information on filters, refer to the Filtering Issues (on page 1034) section. Data type: ResellerTemplateFilter (reseller_template.xsd). The limits node is optional. It is used to request limits policy and limits on using Plesk resources for resellers created with a reseller template. Data type: none. The permissions node is optional. It is used to request permissions settings for resellers created with a reseller template. Data type: none. The ip-pool node is optional. It is used to request for IP pool settings for resellers created with a reseller template. Data type: none. The preferences node is optional. It is used to request preferences for resellers created with a reseller template. Data type: none.

Request Samples
The following packet retrieves information on reseller templates filtered by their names:
<packet version="1.6.0.0"> <reseller-template> <get> <filter> <name>base_template</name> <name>quick_template</name> </filter> <limits/> <permissions/> <ip-pool/> <preferences/> </get> </reseller-template> </packet>

To filter some reseller templates by id and others by name within the same packet, use two get operations:
<packet version="1.6.0.0"> <reseller-template> <get> <filter> <name>base_template</name> <name>quick_template</name> </filter> <limits/> </get> <get> <filter> <id>12</id> </filter> <limits/> </get> </reseller-template> </packet>

Supported Operations

1041

Response Packet Structure


The get node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResellerTemplateOutputResulttype (reseller_template.xsd). The status node is required. It specifies the execution status of the get operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the get operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the get operation fails. It returns the error message. Data type: string. The id node is required if the get operation succeeds, or if the results are filtered by ID. It returns ID of the reseller template which settings are retrieved in the result node. Data type: integer. The name node is required if the get operation succeeds, or if the results are filtered by name. It returns the name of the reseller template which settings are retrieved in the result node. Data type: string. The limits node is required if the request get packet specifies the limits node and the operation succeeds. Data type: resellerLimits (reseller.xsd). To view the structure of this node, refer to the Limits (on page 1031) section.

1042

Supported Operations

The permissions node is required if the request get packet specifies the permissions node and the operation succeeds. Data type: clientPerms (plesk_client.xsd). To view the structure of this node, refer to the Permissions (on page 1032) section. The ip-pool node is required if the request get packet specifies the ip-pool node and the operation succeeds. Data type: ResellerTemplateIpPoolType (reseller_template.xsd). To view the structure of this node, refer to the IP Pool Settings (on page 1033) section. The preferences node is required if the request get packet specifies the preferences node and the operation succeeds. Data type: ResellerTemplatePreferencesType (reseller_template.xsd). To view the structure of this node, refer to the Preferences (on page 1034) section.

Response Samples
A positive response from the server can look as follows:
<packet version="1.6.0.0"> <reseller-template> <get> <result> <status>ok</status> <id>82</id> <name>base_template</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> </result> </get> </reseller-template> </packet>

A negative response from the server can look as follows:


<packet version="1.6.0.0"> <reseller-template> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Template does not exist</errtext> <name>base_template_</name> </result> </get> </reseller-template> </packet>

Supported Operations

1043

Removing Reseller Templates


The del operation is used to remove reseller templates.

In this section:
Request Packet Structure.................................................................................. 1043 Request Samples .............................................................................................. 1044 Response Packet Structure ............................................................................... 1045 Response Samples ........................................................................................... 1046

Request Packet Structure


A request XML packet that removes reseller templates includes the del operation node:
<packet version="1.6.0.0"> <reseller-template> <del> </del> </reseller-template> </packet>

The del node is presented by the ResellerTemplateDelInputType type (reseller_template.xsd):

The filter node is required. It specifies the filtering rule. Data type: ResellerTemplateFilterType (reseller_template.xsd). For information on filters, refer to the Filtering Issues (on page 1034) section.

1044

Supported Operations

Request Samples
The following packet removes reseller templates specified by ID, and by name:
<packet version="1.6.0.0"> <reseller-template> <del> <filter> <name>base_template</name> </filter> </del> <del> <filter> <id>12</id> </filter> </del> </reseller-template> </packet>

The following packet removes all reseller templates from Plesk database:
<packet version="1.6.0.0"> <reseller-template> <del> <filter> <all/> </filter> </del> </reseller-template> </packet>

Supported Operations

1045

Response Packet Structure


The del node of the response packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResellerTemplateOutputResulttype (reseller_template.xsd). The status node is required. It specifies the execution status of the del operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the del operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the del operation fails. It returns the error message. Data type: string. The id node is required if the del operation succeeds, and reseller templates are filtered by ID. It returns ID of the removed reseller template. Data type: id_type (common.xsd). The name node is required if the del operation succeeds, and reseller templates are filtered by name. It returns name of the removed reseller template. Data type: string.

1046

Supported Operations

Response Samples
A positive response from the server can look as follows:
<packet version="1.6.0.0"> <reseller-template> <del> <result> <status>ok</status> <name>base_template</name> </result> </del> </reseller-template> </packet>

A negative response from the server can look as follows:


<packet version="1.6.0.0"> <reseller-template> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>Template does not exist</errtext> </result> </del> </reseller-template> </packet>

Setting Reseller Template Properties


The set operation is used to modify reseller templates. This modification can refer to any or all of the following reseller template settings: limits policy and limits on Plesk resources usage permissions IP pool settings preferences

In this section:
Request Packet Structure.................................................................................. 1047 Request Samples .............................................................................................. 1048 Response Packet Structure ............................................................................... 1048 Response Samples ........................................................................................... 1049

Supported Operations

1047

Request Packet Structure


A request XML packet which changes settings for a specified reseller template includes the set operation node:
<packet version="1.6.0.0"> <reseller-template> <set> </set> </reseller-template> </packet>

The set node is presented by the ResellerTemplateSetInputType complex type (reseller_template.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: ResellerTemplateFilterType (reseller_template.xsd). For information on filters, refer to the Filtering Issues (on page 980) section. The limits node is optional. It specifies limits policy and limits on Plesk resources usage for resellers created with a reseller template. Data type: resellerLimits (reseller.xsd). To view structure of this node, refer to the Limits (on page 1031) section. The permissions node is optional. It specifies permissions for resellers created with a reseller template. Data type: clientPerms (plesk_client.xsd). To view the structure of this node, refer to the Permissions (on page 1032) section. The ip-pool node is optional. It specifies IP pool settings for resellers created with a reseller template. Data type: ResellerTemplateIpPoolType (reseller_template.xsd). To view the structure of this node, refer to the IP Pool Settings (on page 1033) section. The preferences node is optional. It specifies preferences for resellers created with a reseller template. Data type: ResellerTemplatePreferencesType (reseller_template.xsd). To view the structure of this node, refer to the Preferences (on page 1034) section.

1048

Supported Operations

Request Samples
The following set request packet changes IP pool settings for two reseller templates, one specified by id and another by name.
<packet version="1.6.0.0"> <reseller-template> <set> <filter> <id>12</id> </filter> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> <allocate-ip>2</allocate-ip> </ip-pool> </set> <set> <filter> <name>base_template</name> </filter> <ip-pool> <ip-address>192.0.2.121</ip-address> <ip-address>192.0.2.122</ip-address> <allocate-ip>3</allocate-ip> </ip-pool> </set> </reseller-template> </packet>

Response Packet Structure


The set node of the response packet is structured as follows:

Supported Operations

1049

The result node is required. It wraps the response retrieved from the server. Data type: ResellerTemplateOutputResulttype (reseller_template.xsd). The status node is required. It specifies the execution status of the set operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the set operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the set operation fails. It returns the error message. Data type: string. The id node is required if the set operation succeeds. It returns ID of the reseller template which settings were modified. Data type: id_type (common.xsd). The name node is required if the set operation succeeds. It returns name of the reseller template which settings were modified. Data type: string.

Response Samples
A positive response from the server can look as follows:
<packet version="1.6.0.0"> <reseller-template> <set> <result> <status>ok</status> <id>81</id> </result> </set> </reseller-template> </packet>

A negative response from the server can look as follows:


<packet version="1.6.0.0"> <reseller-template> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Template does not exist</errtext> </result> </set> </reseller-template> </packet>

1050

Supported Operations

Managing Secret Keys


Operator: <secret_key> XML Schema: secret_key_input.xsd, secret_key_output.xsd Plesk version: Plesk 7.5.6 Win | Unix 8.0 and later API RPC version: 1.4.0.0 and higher Plesk user: Plesk Administrator Description Plesk Administrator can access Plesk API RPC service using a secret key - alternative way of authentication. Instead of putting the credentials, Plesk Administrator can specify a secret key in the HTTP header of request packets. Note: To create a secret key, you should specify the IP address this secret key will be linked to. Packets sent with this key from different IP's will not be proceeded by Plesk API RPC service. Supported operations

CREATE (see page 1051) creates a secret key GET_INFO (see page 1055) retrieves a secret key DELETE (see page 1059) removes a secret key

In this section:
Creating Secret Key .......................................................................................... 1051 Retrieving Info on Secret Keys .......................................................................... 1055 Removing Secret Key........................................................................................ 1059

Supported Operations

1051

Creating Secret Key


Use the create operation to create a secret key. Note: To create a secret key, you should specify the IP address this secret key will be linked to. Packets sent with this key from different IP's will not be proceeded by Plesk API RPC service.

In this section:
Request Packet Structure.................................................................................. 1051 Request Samples .............................................................................................. 1052 Response Packet Structure ............................................................................... 1053 Response Samples ........................................................................................... 1054

Request Packet Structure


A request XML packet creating a secret key includes the create operation node:
<packet version="1.4.2.0"> <secret_key> <create> ... </create> </secret_key> </packet>

The create node has the following graphical representation:

The ip_address node is required. It specifies the IP address that will be linked to the key. Data type: ip_address (common.xsd). The description node is optional. It specifies additional information about the key. Data type: string.

1052

Supported Operations

Remarks You can create multiple secret keys in a single packet. Add as many create operations as the number of keys to be created.
<create> </create> <create> </create>

Request Samples
Creating a single secret key This packet creates the secret key for IP 192.0.2.3.
<packet version="1.4.2.0"> <secret_key> <create> <ip_address>192.0.2.3</ip_address> </create> </secret_key> </packet>

Creating multiple secret keys This packet creates secret keys for User1, and for User2.
<packet version="1.4.2.0"> <secret_key> <create> <ip_address>192.0.2.2</ip_address> <description>For User1</description> </create> <create> <ip_address>192.0.2.3</ip_address> <description>For User2</description> </create> </secret_key> </packet>

Supported Operations

1053

Response Packet Structure


The create node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the create operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the create operation fails. Data type: integer. The errtext node is optional. It returns the error message if the create operation fails. Data type: string. The key node is optional. It holds the key value if the operation succeeds. Data type: string.

1054

Supported Operations

Response Samples
Creating a single secret key This request packet creates the secret key for IP 192.0.2.1.
<packet version="1.4.2.0"> <secret_key> <create> <ip_address>192.0.2.1</ip_address> </create> </secret_key> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <secret_key> <create> <result> <status>ok</status> <key>6575fae36288be6d1bad40b99808e37f</key> </result> </create> </secret_key> </packet>

Creating multiple secret keys This request packet creates secret keys for User1, and for User2.
<packet version="1.4.2.0"> <secret_key> <create> <ip_address>192.0.2.2</ip_address> <description>For User1</description> </create> <create> <ip_address>192.0.2.3</ip_address> <description>For User2</description> </create> </secret_key> </packet>

Supported Operations

1055

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <secret_key> <create> <result> <status>ok</status> <key>6575fae36288be6d1bad40b99808e37f</key> </result> </create> <create> <result> <status>ok</status> <key>e1b9288a886c82f652921a34ea5e3e62</key> </result> </create> </secret_key> </packet>

Retrieving Info on Secret Keys


Use the get_info operation to retrieve information on secret keys located on the server.

In this section:
Request Packet Structure.................................................................................. 1055 Request Samples .............................................................................................. 1056 Response Packet Structure ............................................................................... 1057 Response Samples ........................................................................................... 1058

Request Packet Structure


A request XML packet retrieving info on secret keys includes the get_info operation node:
<packet version="1.4.2.0"> <secret_key> <get_info> ... </get_info> </secret_key> </packet>

The get_info node has the following graphical representation:

1056

Supported Operations

The filter node is required. It specifies the filtering rule. To retrieve all secret keys located on the server, use the blank filter node (<filter/>). Data type: complex. The key node is optional. To retrieve info on a specified key, set the key value for this node. Data type: string.

Remarks You can retrieve info on multiple secret keys in a single packet. Add as many key parameters to the filter as the number of keys.
<filter> <key></key> <key></key> </filter>

Request Samples
Retrieving info on a secret key This packet retrieves info on secret key 6575fae36288be6d1bad40b99808e37f.
<packet version="1.4.2.0"> <secret_key> <get_info> <filter> <key>6575fae36288be6d1bad40b99808e37f</key> </filter> </get_info> </secret_key> </packet>

Retrieving info on multiple secret keys This packet retrieves info on secret keys 6575def8 and 6576d1ef7.
<packet version="1.4.2.0"> <secret_key> <get_info> <filter> <key>6575def8</key> <key>6576d1ef7</key> </filter> </get_info> </secret_key> </packet>

Supported Operations

1057

This packet retrieves info on all secret keys located on the server.
<packet version="1.4.2.0"> <secret_key> <get_info> <filter/> </get_info> </secret_key> </packet>

Response Packet Structure


The get_info node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_info operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get_info operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get_info operation fails. Data type: string. The key node is optional. It holds the key value if the operation fails. Data type: string. The key_info node is optional. It holds info on the key if the operation succeeds. Data type: SecretKeyInfo (plesk_secretkeys.xsd). The following parameters are nested in the key_info node: The key node is required. It specifies the secret key value. Data type: string. The ip_address node is required. It specifies the IP address linked to the secret key. Data type: ip_address (common.xsd).

1058

Supported Operations

The description node is required. It specifies the secret key description. Data type: string.

Response Samples
Retrieving info on a secret key This request packet retrieves info on secret key 6575fae36288be6d1bad40b99808e37f.
<packet version="1.4.2.0"> <secret_key> <get_info> <filter> <key>6575fae36288be6d1bad40b99808e37f</key> </filter> </get_info> </secret_key> </packet>

If the key was found on the server, a response can look as follows:
<packet version="1.4.2.0"> <secret_key> <get_info> <result> <status>ok</status> <key_info> <key>6575fae36288be6d1bad40b99808e37f</key> <ip_address>192.0.2.1</ip_address> <description></description> </key_info> </result> </get_info> </secret_key> </packet>

If the key was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <secret_key> <get_info> <result> <status>error</status> <errcode>1013</errcode> <errtext>Key is not found</errtext> <key>6575fae36288be6d1bad40b99808e37f</key> </result> </get_info> </secret_key> </packet>

Supported Operations

1059

Retrieving info on multiple secret keys This request packet retrieves info on secret keys 6575def8 and 6576d1ef7.
<packet version="1.4.2.0"> <secret_key> <get_info> <filter> <key>6575def8</key> <key>6576d1ef7</key> </filter> </get_info> </secret_key> </packet>

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <secret_key> <get_info> <result> <status>ok</status> <key_info> <key>6575def8</key> <ip_address>192.0.2.1</ip_address> <description>For User3</description> </key_info> </result> <result> <status>ok</status> <key_info> <key>6576d1ef7</key> <ip_address>192.0.2.2</ip_address> <description></description> </key_info> </result> </get_info> </secret_key> </packet>

1060

Supported Operations

Removing Secret Key


Use the delete operation to remove a specified secret key from the server.

In this section:
Request Packet Structure.................................................................................. 1060 Request Samples .............................................................................................. 1061 Response Packet Structure ............................................................................... 1062 Response Samples ........................................................................................... 1063

Request Packet Structure


A request XML packet removing a secret key includes the delete operation node:
<packet version="1.4.2.0"> <secret_key> <delete> ... </delete> </secret_key> </packet>

The delete node has the following graphical representation:

The filter node is required. It specifies the filtering rule. To remove all secret keys located on the server, use the blank filter node (<filter/>). Data type: complex. The key node is optional. To remove a specified key, set the key value for this node. Data type: string.

Remarks You can remove multiple secret keys in a single packet. Add as many key parameters to the filter as the number of keys to be removed.
<filter> <key></key> <key></key> </filter>

Supported Operations

1061

Request Samples
Removing a secret key This packet removes secret key 6575fae36288be6d1bad40b99808e37f.
<packet version="1.4.2.0"> <secret_key> <delete> <filter> <key>6575fae36288be6d1bad40b99808e37f</key> </filter> </delete> </secret_key> </packet>

Removing multiple secret keys This packet removes secret keys 6575def8 and 6576d1ef7.
<packet version="1.4.2.0"> <secret_key> <remove> <filter> <key>6575def8</key> <key>6576d1ef7</key> </filter> </remove> </secret_key> </packet>

This packet removes all secret keys from the server.


<packet version="1.4.2.0"> <secret_key> <delete> <filter/> </delete> </secret_key> </packet>

1062

Supported Operations

Response Packet Structure


The delete node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the delete operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the delete operation fails. Data type: integer. The errtext node is optional. It returns the error message if the delete operation fails. Data type: string. The key node is optional. It holds the key value if the operation succeeds. Data type: string.

Supported Operations

1063

Response Samples
Removing a secret key This request packet removes secret key 6575fae36288be6d1bad40b99808e37f.
<packet version="1.4.2.0"> <secret_key> <delete> <filter> <key>6575fae36288be6d1bad40b99808e37f</key> </filter> </delete> </secret_key> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <secret_key> <delete> <result> <status>ok</status> <key>6575fae36288be6d1bad40b99808e37f</key> </result> </delete> </secret_key> </packet>

If the key was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <secret_key> <delete> <result> <status>error</status> <errcode>1013</errcode> <errtext>Secret key does not exist</errtext> <key>6575fae36288be6d1bad40b99808e37f</key> </result> </delete> </secret_key> </packet>

1064

Supported Operations

Removing multiple secret keys This request packet removes secret keys 6575def8 and 6576d1ef7.
<packet version="1.4.2.0"> <secret_key> <remove> <filter> <key>6575def8</key> <key>6576d1ef7</key> </filter> </remove> </secret_key> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <secret_key> <delete> <result> <status>ok</status> <key>6575def8</key> </result> <result> <status>ok</status> <key>6576d1ef7</key> </result> </delete> </secret_key> </packet>

Supported Operations

1065

Managing Sessions
Operator: <session> XML Schema: session.xsd Plesk version: 8.1.1 API RPC version: 1.5.0.0 Plesk user: Plesk Administrator Description Control panel session (CP session) is a lasting connection between a Plesk user and Plesk GUI. The session operator is used to manage CP sessions. Supported operations:

GET (on page 1065) retrieves list of currently opened sessions and information on each opened session TERMINATE (on page 1068) closes a specified session

In this section:
Retrieving Sessions List .................................................................................... 1065 Terminating Session.......................................................................................... 1068

Retrieving Sessions List


Use the get operation to retrieve list of currently opened CP sessions and information on each opened session.

In this section:
Request Packet ................................................................................................. 1066 Response Packet Structure ............................................................................... 1066 Response Samples ........................................................................................... 1067

1066

Supported Operations

Request Packet
A request XML packet retrieving list of currently opened CP sessions and information on each opened session includes the get operation node:
<packet version="1.5.0.0"> <session> <get/> </session> </packet>

The get node is required. Data type: none.

Response Packet Structure


The get node of the output XML packet is presented by type SessionGetOutputType (updater.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get operation fails. Data type: string.

Supported Operations

1067

The session node is optional. It holds parameters of opened CP sessions. Data type: Session (session.xsd).

If the session node is present in the response packet, the following nodes are required: The id node specifies the session ID. Data type: string. The type node specifies type of user who has started the session. Data type: string. Allowed values: admin | reseller | domain-admin | mail-user | client. The ip-address node specifies the user's IP address. Data type: ip_address (common.xsd) The login node holds the user login name. Data type: string. The login-time node specifies the moment when the session was started. Data type: date. The idle node specifies the moment when the last action was performed by the user. Data type: date.

1068

Supported Operations

Response Samples
A possible response from the server can look as follows:
<packet version="1.5.0.0"> <session> <get> <result> <status>ok</status> <session> <id>6a17d01f5e1925601faa86ad22ada6ff</id> <type>admin</type> <ip-address>192.0.2.1</ip-address> <login>admin</login> <login-time>2007-02-20T05:21:00</login-time> <idle>2007-02-20T05:37:42</idle> </session> <session> <id>f15cabb0a544df13aee1ee5b55de0530</id> <type>JimmyJoe</type> <ip-address>192.0.2.2</ip-address> <login>client</login> <login-time>2007-02-21T23:42:00</login-time> <idle>2007-02-21T23:43:22</idle> </session> </result> </get> </session> </packet>

Terminating Session
Use the terminate operation to close a specified session.

In this section:
Request Packet Structure.................................................................................. 1069 Request Samples .............................................................................................. 1069 Response Packet Structure ............................................................................... 1070 Response Samples ........................................................................................... 1071

Supported Operations

1069

Request Packet Structure


A request XML packet terminating a specified session includes the terminate operation node:
<packet version="1.5.0.0"> <session> <termination> ... </termination> </session> </packet>

The terminate node is presented by type SessionTerminateInput (session.xsd) and has the following graphical representation:

The session-id node is required. It specifies the session ID. For info on how to retrieve the session ID, refer to the Retrieving Sessions List (on page 1065) section. Data type: string.

Request Samples
The request packet terminating the session with ID a66734b looks as follows:
<packet version="1.5.0.0"> <session> <terminate> <session-id>a66734b</session-id> </terminate> </session> </packet>

1070

Supported Operations

Response Packet Structure


The terminate node of the output XML packet is presented by type SessionTerminateOutput (session.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the terminate operation fails. Data type: integer. The errtext node is optional. It returns the error message if the terminate operation fails. Data type: string.

Supported Operations

1071

Response Samples
Request packet sample The request packet terminating the session win ID a66734b looks as follows:
<packet version="1.5.0.0"> <session> <terminate> <session-id>a66734b</session-id> </terminate> </session> </packet>

Response packet samples A positive response from the server looks as follows:
<packet version="1.5.0.0"> <session> <terminate> <result> <status>ok</status> </result> </terminate> </session> </packet>

If the session was not found on the server, the response looks as follows:
<packet version="1.5.0.0"> <session> <terminate> <result> <status>error</status> <errcode>1013</errcode> <errtext>Session does not exist</errtext> </result> </terminate> </session> </packet>

1072

Supported Operations

Managing Web Applications


Operator: <siteapp> XML Schema: siteapp_input.xsd, siteapp_output.xsd Plesk version: Plesk 7.5.2 for Unix and later API RPC version: all versions Plesk user: Plesk Administrator Description Plesk comes with a number of free and commercial Web applications (web-based software applications) that can be provided to clients and deployed on their domains. The applications are stored in the Application Vault in the form of installation packages. Each application package is uniquely identified by ID. Client accounts can have their own Application Vault modules (for which they should buy a license), thus being able to manage their own list of packages. These users can also create their own applications and add them to the Application Vault. The client's Application Vault module is called Application pool. Operations on the Application Vault via API RPC are allowed to Plesk Administrator only. Different versions of the same Web application are treated as different Web applications from the administrative standpoint.

In this section:
History of Changes ............................................................................................ 1074 Web Application Properties ............................................................................... 1075 Retrieving List of All Web Applications .............................................................. 1076 Viewing Application Pool ................................................................................... 1079 Adding Web Application to Application Pool ...................................................... 1083 Removing Web Applications.............................................................................. 1087 Retrieving List of Packages Available For Domain ............................................ 1091 Changing Properties of Web Application ........................................................... 1096 Retrieving Web application Requirements ......................................................... 1100 Installing Web Application ................................................................................. 1106

Supported Operations

1073

Supported operations:

GET_ALL_PACKAGES_LIST (on page 1076) retrieves the list of all Web applications available on Plesk GET_PACKAGES_LIST_BY_CLIENT (see page 1079) retrieves the list of Web applications from Application pool of the specified client ADD_PACKAGES_TO_CLIENT_POOL (see page 1083) adds Web applications to Application pool of the specified client REMOVE_PACKAGES_FROM_CLIENT_POOL (see page 1087) removes Web applications from Application pool of the specified client GET_PACKAGES_LIST_BY_DOMAIN (see page 1091) retrieves the list of Web applications available for the specified domain SET_PACKAGE_PROPERTIES (see page 1096) sets the free or commercial property for the specified Web application GET_PACKAGE_REQUIREMENTS (see page 1100) retrieves the requirement information for the specified Web applications INSTALL_PACKAGES (see page 1106) installs a Web application

1074

Supported Operations

History of Changes
The table below shows a list of changes made to the siteapp operator starting from version 1.3.5.1 of the API RPC protocol.
Version Data type of the filter node (siteapp_input.x sd) Type of the package_id parameter in the filter node. Type of the Data type of the package_id node in package node. the operationResultTyp e (siteapp_output .xsd) required packageDescription Type (siteapp_output .xsd) siteappDescriptionT ype (plesk_siteapp. xsd) siteappDescriptionT ype (plesk_siteapp. xsd) siteappDescriptionT ype (plesk_siteapp. xsd) siteappDescriptionT ype (plesk_siteapp. xsd)

1.3.5.1

filterType (siteapp_input.x sd) siteappFilterType (siteapp_input.x sd) none

optional

1.4.0.0

optional

required

1.4.1.0

required

required

1.4.1.1, 1.4.1.2

siteappFilterType (siteapp_input.x sd)

optional

optional

1.4.2.0 none and later versions

required

required

Supported Operations

1075

Web Application Properties


Every Web application in Plesk has its own properties, nested in the package node. The package is presented by type siteappDescriptionType (plesk_siteapp.xsd), and its graphical representation is as follows:

The id node is required. It specifies the Web application ID in Plesk Application Vault. Data type: integer. The name node is required. It specifies the Web application name in Plesk Application Vault. Data type: string. The version node is required. It specifies the version of the Web application. Data type: string. The release node is required. It specifies the number of releases of the Web application. Data type: integer. The description node is required. It specifies the descriptive information about the Web application. Data type: string. The license node is required. It specifies if the license key for the Web application is present and valid. Data type: string. Allowed values: ok | problem | free. The access_level node is required. It specifies whether the Web application is free or commercial. Data type: string. Allowed values: free | commercial. The instance node is optional. It specifies the number of copies of the Web application installed on clients domains (web sites). Data type: integer.

Remarks

1076

Supported Operations

A set of Web application properties can look as follows:


<id>1</id> <name>bbclone</name> <version>0.4.8a</version> <release>3</release> <description> Feature rich counter </description> <license>free</license> <access_level>free</access_level> <instance>0</instance>

Retrieving List of All Web Applications


Use the get_all_packages_list operation to retrieve the list of all Web applications from Plesk Application Vault.

In this section:
Request Packet ................................................................................................. 1076 Response Packet Structure ............................................................................... 1077 Response Samples ........................................................................................... 1078

Request Packet
A request XML packet retrieving the list of all Web applications from Plesk Application Vault includes the get_all_packages_list operation node:
<packet version="1.4.2.0"> <siteapp> <get_all_packages_list/> </siteapp> </packet>

The get_all_packages_list node has the following graphical representation:

Request packet sample The request packet, that retrieves the list of all Web applications from Plesk Application Vault, looks as follows:
<packet version="1.4.2.0"> <siteapp> <get_all_packages_list/> </siteapp> </packet>

Supported Operations

1077

Response Packet Structure


The get_all_packages_list node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_all_packages_list operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get_all_packages_list operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get_all_packages_list operation fails. Data type: string. The package node is optional. It returns the Web application properties. Data type: siteappDescriptionType (plesk_siteapp.xsd). For information on Web application properties, please refer to the Web Application Properties (on page 1075) section.

Note: The description of this node differs from version to version of the protocol. For information, refer to the History of Changes (see page 1074) section.

1078

Supported Operations

Response Samples
Request sample This request packet retrieves the list of all Web applications from Plesk Application Vault.
<packet version="1.4.2.0"> <siteapp> <get_all_packages_list/> </siteapp> </packet>

Response sample A possible response from the server can look as follows:
<packet version="1.4.2.0"> <siteapp> <get_all_packages_list> <result> <status>ok</status> <package> <id>1</id> <name>bbclone</name> <version>0.4.8a</version> <release>3</release> <description> Feature rich counter </description> <license>free</license> <access_level>free</access_level> <instance>0</instance> </package> <package> <id>2</id> <name>gtchat</name> <version>0.93</version> <release>20</release> <description> Web Chat </description> <license>free</license> <access_level>free</access_level> <instance>0</instance> </package> </result> </get_all_packages_list> </siteapp> </packet>

Supported Operations

1079

Viewing Application Pool


Use the get_packages_list_by_client operation to retrieve all Web applications from the Application pool of the specified client.

In this section:
Request Packet Structure.................................................................................. 1079 Request Samples .............................................................................................. 1080 Response Packet Structure ............................................................................... 1080 Response Samples ........................................................................................... 1081

Request Packet Structure


A request XML packet retrieving the list of all Web applications from the Application pool of the specified client includes the get_packages_list_by_client operation node:
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> ... </get_packages_list_by_client> </siteapp> </packet>

The get_packages_list_by_client node has the following graphical representation:

The client_id node is required. It specifies the client ID in Plesk database. Data type: integer.

Remarks You can retrieve lists of Web applications of multiple clients in a single packet. Add as many get_packages_list_by_client operations as the number of clients which lists are to be viewed.
<siteapp> <get_packages_list_by_client> </get_packages_list_by_client> ... <get_packages_list_by_client> </get_packages_list_by_client> </siteapp>

1080

Supported Operations

Request Samples
Retrieving packages list of a single client This packet retrieves the list of all Web applications of the client specified by ID 5.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <client_id>5</client_id> </get_packages_list_by_client> </siteapp> </packet>

Retrieving packages list of multiple clients This packet retrieves lists of all Web applications of the clients specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <client_id>5</client_id> </get_packages_list_by_client> <get_packages_list_by_client> <client_id>7</client_id> </get_packages_list_by_client> </siteapp> </packet>

Response Packet Structure


The get_packages_list_by_client node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).

Supported Operations

1081

The status node is required. It specifies the execution status of the get_packages_list_by_client operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get_packages_list_by_client operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get_packages_list_by_client operation fails. Data type: string. The package node is optional. It returns the Web application preferences. Data type: siteappDescriptionType (plesk_siteapp.xsd). For information on Web application preferences, refer to the Web Application Properties (on page 1075) section.

Note: The node differs from version to version of the protocol. For more information, refer to the History of Changes (see page 1074) section.

Response Samples
Retrieving packages list of a single client This request packet retrieves the list of all Web applications of the client specified by ID 5.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <client_id>5</client_id> </get_packages_list_by_client> </siteapp> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <result> <status>ok</status> <package> <id>1</id> <name>bbclone</name> <version>0.4.8a</version> <release>3</release> <description> Feature rich counter </description> <license>free</license> <access_level>free</access_level> <instance>1</instance> </package> </result> </get_packages_list_by_client> </siteapp> </packet>

1082

Supported Operations

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <result> <status>error</status> <status>1013</status> <status>Client does not exist</status> </result> </get_packages_list_by_client> </siteapp> </packet>

Retrieving packages list of multiple clients This request packet retrieves lists of all Web applications of the clients specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <client_id>5</client_id> </get_packages_list_by_client> <get_packages_list_by_client> <client_id>7</client_id> </get_packages_list_by_client> </siteapp> </packet>

If the first client has two Web applications and the second client was not found, a response from the server can look as follows:
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_client> <result> <status>ok</status> <package> <id>1</id> <name>bbclone</name> <version>0.4.8a</version> <release>3</release> <description> Feature rich counter </description> <license>free</license> <access_level>free</access_level> <instance>1</instance> </package> <package> <id>2</id> <name>Ychat</name> <version>0.7.1b</version> <release>7</release> <description> Feature rich chat </description> <license>free</license> <access_level>free</access_level> <instance>3</instance>

Supported Operations </package> </result> </get_packages_list_by_client> <get_packages_list_by_client> <result> <status>error</status> <status>1013</status> <status>Client does not exist</status> </result> </get_packages_list_by_client> </siteapp>

1083

Adding Web Application to Application Pool


Use the add_packages_to_client_pool operation to add Web applications to the client specified by ID.

In this section:
Request Packet Structure.................................................................................. 1083 Request Samples .............................................................................................. 1084 Response Packet Structure ............................................................................... 1085 Response Samples ........................................................................................... 1086

Request Packet Structure


A request XML packet adding Web applications to the Application pool of the specified client includes the add_packages_to_client_pool operation node:
<packet version="1.4.2.0"> <add_packages_to_client_pool> ... </add_packages_to_client_pool> </packet>

The add_packages_to_client_pool node has the following graphical representation:

The client_id node is required. It specifies the client ID in Plesk database. Data type: integer. The filter node is required. It specifies the filtering rule. Data type: complex. Note: The node differs from version to version of the protocol. For more information, refer to the History of Changes (see page 1074) section.

1084

Supported Operations

The package_id is required. It specifies the Web application ID in Plesk Application Vault. Data type: integer. Note: The node differs from version to version of the protocol. For more information, refer to the History of Changes (see page 1074) section.

Remarks You can add multiple Web applications to the specified Application pool in a single packet. Add as many package_id parameters as the number of Web applications to be added.
<filter> <package_id>...</package_id> <package_id>...</package_id> </filter>

Request Samples
Adding a single Web application This packet adds the Web application specified by ID 1 to the client specified by ID 45.
<packet version="1.4.2.0"> <add_packages_to_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> </filter> </add_packages_to_client_pool> </packet>

Adding multiple Web applications This packet adds Web applications specified by ID 1 and ID 3 to the client specified by ID 45.
<packet version="1.4.2.0"> <add_packages_to_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> <package_id>3</package_id> </filter> </add_packages_to_client_pool> </packet>

Supported Operations

1085

Response Packet Structure


The add_packages_to_client_pool node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: operationResultType (siteapp_output.xsd). The status node is required. It specifies the execution status of the add_packages_to_client_pool operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add_packages_to_client_pool operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add_packages_to_client_pool operation fails. Data type: string. The package_id node is required. It returns the Web application ID in Plesk Application Vault. Data type: integer.

Note: The description of this node differs from version to version of the protocol. For information, refer to the History of Changes (see page 1074) section.

1086

Supported Operations

Response Samples
Adding a single Web application This request packet adds the Web application specified by ID 1 to the client specified by ID 45.
<packet version="1.4.2.0"> <add_packages_to_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> </filter> </add_packages_to_client_pool> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <add_packages_to_client_pool> <result> <status>ok</status> <package_id>1</package_id> </result> </add_packages_to_client_pool> </packet>

If the Web application with ID 1 was not found in Plesk Application Vault, the response from the server looks as follows:
<packet version="1.4.2.0"> <add_packages_to_client_pool> <result> <status>error</status> <status>1013</status> <status>Unable to get package: package does not exist</status> <package_id>1</package_id> </result> </add_packages_to_client_pool> </packet>

Adding multiple Web applications This request packet adds the Web applications specified by ID 1 and ID 3 to the client specified by ID 45.
<packet version="1.4.2.0"> <add_packages_to_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> <package_id>3</package_id> </filter> </add_packages_to_client_pool></packet>

Supported Operations

1087

A possible response from the server can look as follows:


<add_packages_to_client_pool> <result> <status>ok</status> <package_id>1</package_id> </result> <result> <status>error</status> <status>1013</status> <status>Web application does not exist</status> <package_id>1</package_id> </result> </add_packages_to_client_pool>

Removing Web Applications


Use the remove_packages_from_client_pool operation to remove the specified Web applications from the Application pool of the specified client.

In this section:
Request Packet Structure.................................................................................. 1087 Request Samples .............................................................................................. 1088 Response Packet Structure ............................................................................... 1089 Response Samples ........................................................................................... 1090

Request Packet Structure


A request XML packet removing Web applications from the Application pool of the specified client includes the remove_packages_from_client_pool operation node:
<packet version="1.4.2.0"> <remove_packages_from_client_pool> ... </remove_packages_from_client_pool> </packet>

The remove_packages_from_client_pool node has the following graphical representation:

The client_id node is required. It specifies the client ID in Plesk database. Data type: integer.

1088

Supported Operations

The filter node is required. It specifies the filtering rule. Data type: complex.

Note: The description of this node differs from version to version of the protocol. For information, refer to the History of Changes (see page 1074) section. The package_id is optional. It specifies the Web application ID in Plesk Application Vault. Data type: integer.

Note: To remove all Web applications from the Application pool, use the blank filter (<filter/>). Remarks You can remove multiple Web applications from the Application pool in a single packet. Add as many package_id parameters as the number of Web applications to be removed.
<filter> <package_id>...</package_id> <package_id>...</package_id> </filter>

Request Samples
Removing a single Web application This packet removes the Web application specified by ID 1 from the Application pool of the client specified by ID 45.
<packet version="1.4.2.0"> <remove_packages_from_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> </filter> </remove_packages_from_client_pool> </packet>

Removing multiple Web applications This packet removes Web applications specified by ID 1 and ID 3 from the Application pool of the client specified by ID 45.
<packet version="1.4.2.0"> <remove_packages_from_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> <package_id>3</package_id> </filter> </remove_packages_from_client_pool> </packet>

Supported Operations

1089

Removing all Web applications This packet removes all Web applications from the Application pool of the client specified by ID 45.
<packet version="1.4.2.0"> <remove_packages_from_client_pool> <client_id>45</client_id> <filter/> </remove_packages_from_client_pool> </packet>

Response Packet Structure


The remove_packages_from_client_pool node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: operationResultType (siteapp_output.xsd). The status node is required. It specifies the execution status of the remove_packages_from_client_pool operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the remove_packages_from_client_pool operation fails. Data type: integer. The errtext node is optional. It returns the error message if the remove_packages_from_client_pool operation fails. Data type: string. The package_id node is required. It returns the Web application ID in Plesk Application Vault. Data type: integer.

Note: The description of this node differs from version to version of the protocol. For information, refer to the History of Changes (see page 1074) section.

1090

Supported Operations

Response Samples
Removing a single Web application This request packet removes the Web application specified by ID 1 from the Application pool of the client specified by ID 45.
<packet version="1.4.2.0"> <remove_packages_from_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> </filter> </remove_packages_from_client_pool> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <remove_packages_from_client_pool> <result> <status>ok</status> <package_id>1</package_id> </result> </remove_packages_from_client_pool> </packet>

If the client with ID 45 was not found in Plesk database, the response from the server looks as follows:
<packet version="1.4.2.0"> <remove_packages_from_client_pool> <result> <status>error</status> <errcode>1015</errcode> <errtext>Client does not exist</errtext> <package_id>1</package_id> </result> </remove_packages_from_client_pool> </packet>

Removing multiple Web applications This request packet removes Web applications specified by ID 1 and ID 3 from the Application pool of the client specified by ID 45.
<packet version="1.4.2.0"> <remove_packages_from_client_pool> <client_id>45</client_id> <filter> <package_id>1</package_id> <package_id>3</package_id> </filter> </remove_packages_from_client_pool></packet>

Supported Operations

1091

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <remove_packages_from_client_pool> <result> <status>ok</status> <package_id>1</package_id> </result> <result> <status>ok</status> <package_id>3</package_id> </result> </remove_packages_from_client_pool> </packet>

Retrieving List of Packages Available For Domain


Use the get_packages_list_by_domain operation to retrieve the list of all Web applications available for the specified domain.

In this section:
Request Packet Structure.................................................................................. 1091 Request Samples .............................................................................................. 1092 Response Packet Structure ............................................................................... 1093 Response Samples ........................................................................................... 1094

Request Packet Structure


A request XML packet retrieving the list of Web applications available for the specified domain includes the get_packages_list_by_domain operation node:
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> ... </get_packages_list_by_domain> </siteapp> </packet>

The get_packages_list_by_domain node has the following graphical representation:

The domain_id node is required. It specifies the domain ID in Plesk database. Data type: integer.

1092

Supported Operations

Remarks You can retrieve lists of Web applications available for the specified domain in a single packet. Add as many get_packages_list_by_domain operations as the number of domains which lists are to be viewed.
<siteapp> <get_packages_list_by_domain> </get_packages_list_by_domain> ... <get_packages_list_by_domain> </get_packages_list_by_domain> </siteapp>

Request Samples
Retrieving list of packages for a single domain This packet retrieves the list of all Web applications available for the domain specified by ID 5.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <domain_id>5</domain_id> </get_packages_list_by_domain> </siteapp> </packet>

Retrieving list of packages for multiple domains This packet retrieves lists of all Web applications available for the domains specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <domain_id>5</domain_id> </get_packages_list_by_domain> <get_packages_list_by_domain> <domain_id>7</domain_id> </get_packages_list_by_domain> </siteapp> </packet>

Supported Operations

1093

Response Packet Structure


The get_packages_list_by_domain node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_packages_list_by_domain operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get_packages_list_by_domain operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get_packages_list_by_domain operation fails. Data type: string. The package node is optional. It returns the Web application preferences. Data type: siteappDescriptionType (plesk_siteapp.xsd). For information on Web application preferences, refer to the Web Application Properties (on page 1075) section.

Note: The node differs from version to version of the protocol. For more information, refer to the History of Changes (see page 1074) section.

1094

Supported Operations

Response Samples
Retrieving list of packages for a single domain This request packet retrieves the list of all Web applications available for the domain specified by ID 5.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <domain_id>5</domain_id> </get_packages_list_by_domain> </siteapp> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <result> <status>ok</status> <package> <id>1</id> <name>bbclone</name> <version>0.4.8a</version> <release>3</release> <description> Feature rich counter </description> <license>free</license> <access_level>free</access_level> <instance>0</instance> </package> </result> </get_packages_list_by_domain> </siteapp> </packet>

If the domain was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <result> <status>error</status> <status>1015</status> <status>Domain does not exist</status> </result> </get_packages_list_by_domain> </siteapp> </packet>

Supported Operations

1095

Retrieving list of packages for multiple domains This request packet retrieves lists of all Web applications available for the domains specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <domain_id>5</domain_id> </get_packages_list_by_domain> <get_packages_list_by_domain> <domain_id>7</domain_id> </get_packages_list_by_domain> </siteapp> </packet>

If the first domain was not found, and the second domain has two Web applications available for installation, a response from the server can look as follows:
<packet version="1.4.2.0"> <siteapp> <get_packages_list_by_domain> <result> <status>error</status> <status>1015</status> <status>Domain does not exist</status> </result> </get_packages_list_by_domain> <get_packages_list_by_domain> <result> <status>ok</status> <package> <id>1</id> <name>bbclone</name> <version>0.4.8a</version> <release>3</release> <description> Feature rich counter </description> <license>free</license> <access_level>free</access_level> <instance>0</instance> </package> <package> <id>2</id> <name>Ychat</name> <version>0.7.8a</version> <release>3</release> <description> Feature rich chat </description> <license>free</license> <access_level>free</access_level> <instance>1</instance> </package> </result> </get_packages_list_by_domain> </siteapp> </packet>

1096

Supported Operations

Changing Properties of Web Application


A Web application can be free or commercial. All free Web application packages are automatically added to all Application pools. However, paid Web applications can be added to the client's pool only upon purchase. When you change a free Web application into a commercial one, it is withdrawn from Application pools of all clients. Now only administrator can add this application to client's application pools when needed. When you change a commercial application into a free one, it becomes free of charge for all clients. Use the set_package_properties operation to change the access level for the specified Web application.

In this section:
Request Packet Structure.................................................................................. 1096 Request Samples .............................................................................................. 1097 Response Packet Structure ............................................................................... 1098 Response Samples ........................................................................................... 1099

Request Packet Structure


A request XML packet changing Web application properties includes the set_package_properties operation node:
<packet version="1.4.2.0"> <set_package_properties> ... </set_package_properties> </packet>

The set_package_properties node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: complex. Note: The node differs from version to version of the protocol. For more information, refer to the History of Changes (see page 1074) section.

The package_id node is optional. It specifies the Web application ID in Plesk Application Vault. Data type: integer.

Supported Operations

1097

The properties node is required. It specifies properties of the Web application. Data type: none. The access_level node is optional. It specifies if the Web application is free or commercial. Data type: string. Allowed values: free | commercial. Note: To change properties of all Web applications, use the blank filter (<filter/>).

Remarks You can change properties of multiple Web applications in a single packet. Add as many package_id parameters as the number of Web applications to be affected.
<filter> <package_id>...</package_id> <package_id>...</package_id> </filter>

Request Samples
Changing properties of a single Web application This packet makes the Web application specified by ID 1 available for all clients.
<packet version="1.4.2.0"> <set_package_properties> <filter> <package_id>1</package_id> </filter> <properties> <access_level>free</access_level> </properties> </set_package_properties> </packet>

Changing properties of multiple Web applications This packet requests for commercial use of Web applications specified by ID 1 and ID 4.
<packet version="1.4.2.0"> <set_package_properties> <filter> <package_id>1</package_id> <package_id>4</package_id> </filter> <properties> <access_level>commercial</access_level> </properties> </set_package_properties> </packet>

1098

Supported Operations

Changing properties of all Web applications This packet makes all Web applications available for all clients.
<packet version="1.4.2.0"> <set_package_properties> <filter/> <properties> <access_level>free</access_level> </properties> </set_package_properties> </packet>

Response Packet Structure


The set_package_properties node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: operationResultType (siteapp_output.xsd). The status node is required. It specifies the execution status of the set_package_properties operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set_package_properties operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set_package_properties operation fails. Data type: string. The package_id node is required. It returns the Web application ID in Plesk Application Vault. Data type: integer.

Note: The node differs from version to version of the protocol. For more information, refer to the History of Changes (see page 1074) section.

Supported Operations

1099

Response Samples
Changing preferences of a single Web application This request packet makes the Web application specified by ID 1 available for all clients.
<packet version="1.4.2.0"> <set_package_properties> <filter> <package_id>1</package_id> </filter> <properties> <access_level>free</access_level> </properties> </set_package_properties> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <set_package_properties> <result> <status>ok</status> <package_id>1</package_id> </result> </set_package_properties> </packet>

If the Web application with ID 1 was not found on the server, the response from the server looks as follows:
<packet version="1.4.2.0"> <set_package_properties> <result> <status>error</status> <status>1013</status> <status>Web application does not exist</status> </result> </set_package_properties> </packet>

1100

Supported Operations

Changing preferences of multiple Web applications This packet requests for commercial use of Web applications specified by ID 1 and ID 4.
<packet version="1.4.2.0"> <set_package_properties> <filter> <package_id>1</package_id> <package_id>4</package_id> </filter> <properties> <access_level>commercial</access_level> </properties> </set_package_properties> </packet>

If the operation succeeds, the response from the server looks as follows:
<packet version="1.4.2.0"> <set_package_properties> <result> <status>ok</status> <package_id>1</package_id> </result> <result> <status>ok</status> <package_id>1</package_id> </result> </set_package_properties> </packet>

Retrieving Web application Requirements


Use the get_package_requirements operation to retrieve the list of requirements to be met by a client for successful installation and usage of the specified Web application.

In this section:
Request Packet Structure.................................................................................. 1101 Request Samples .............................................................................................. 1101 Response Packet Structure ............................................................................... 1103 Response Samples ........................................................................................... 1104

Supported Operations

1101

Request Packet Structure


A request XML packet retrieving the list of a Web application requirements includes the get_package_requirements operation node:
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> ... </get_packages_requirements> </siteapp> </packet>

The get_package_requirements node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: complex. The package_id node is optional. It specifies the Web application ID in Plesk Application Vault. Data type: integer.

Note: To retrieve lists of requirements for all Web applications, use the blank filter (<filter/>). Remarks You can retrieve requirements for multiple Web applications in a single packet. Add as many package_id parameters as the number of Web applications which requirements are to be retrieved.
<filter> <package_id>...</package_id> <package_id>...</package_id> </filter>

Request Samples
Retrieving requirements for a single Web application This packet retrieves the list of requirements for the Web application specified by ID 5.
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <filter> <package_id>5</package_id> </filter> </get_packages_requirements> </siteapp> </packet>

1102

Supported Operations

Retrieving requirements for multiple Web applications This packet retrieves lists of requirements for the Web applications specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <filter> <package_id>5</package_id> <package_id>7</package_id> </filter> </get_packages_requirements> </siteapp> </packet>

Retrieving requirements for all Web applications This packet retrieves lists of requirements for all Web applications.
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <filter/> </get_packages_requirements> </siteapp> </packet>

Supported Operations

1103

Response Packet Structure


The get_package_requirements node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_package_requirements operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get_package_requirements operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get_package_requirements operation fails. Data type: string. The package_id node is required. It returns the Web application ID in Plesk Application Vault. Data type: integer. The requirement node is optional. It holds the requirement for the specified Web application. Data type: none. It is structured as follows:

The name node is required. If the requirement node is not blank, it specifies the name of requirement for the specified Web application. Data type: string. The type node is required. If the requirement node is not blank, it specifies the type of requirement for the specified Web application. Data type: string. The value node is required. If the requirement node is not blank, it specifies the value of requirement for the specified Web application. Data type: string.

1104

Supported Operations

Response Samples
Retrieving requirements for a sing Web application This request packet retrieves the list of requirements for the Web application specified by ID 5.
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <filter> <package_id>5</package_id> </filter> </get_packages_requirements> </siteapp> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <result> <status>ok</status> <package_id>5</package_id> <requirement> <name>Disk space</name> <type>Limit</type> <value>4.81 MB</value> </requirement> </result> </get_packages_requirements> </siteapp> </packet>

If the package was not found in Plesk Application Vault, the positive response from the server looks as follows:
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <result> <status>error</status> <errcode>1013</errcode> <errtext>Unable to get package: package does not exist</errtext> <package_id>5</package_id> </result> </get_packages_requirements> </siteapp> </packet>

Supported Operations

1105

Retrieving requirements for multiple Web applications This request packet retrieves lists of requirements for the Web applications specified by ID 5 and ID 7.
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <filter> <package_id>5</package_id> <package_id>7</package_id> </filter> </get_packages_requirements> </siteapp> </packet>

If the package with ID 5 was not found in Plesk Application Vault, and the list of requirements for the package with ID 7 was successfully retrieved, a response from the server can look as follows:
<packet version="1.4.2.0"> <siteapp> <get_packages_requirements> <result> <status>error</status> <errcode>1013</errcode> <errtext>Unable to get package: package does not exist</errtext> <package_id>5</package_id> </result> <result> <status>ok</status> <package_id>5</package_id> <requirement> <name>Disk space</name> <type>Limit</type> <value>4.81 MB</value> </requirement> </result> </get_packages_requirements> </siteapp> </packet>

1106

Supported Operations

Installing Web Application


Use the install_packages operation to add the specified Web application to Plesk Application Vault. Before the installation, Web applications should be uploaded to Plesk server. For information on uploading packages to Plesk, refer to the Managing Upload (see page 1368) section.

In this section:
Request Packet Structure.................................................................................. 1106 Request Samples .............................................................................................. 1107 Response Packet Structure ............................................................................... 1108 Response Samples ........................................................................................... 1109

Request Packet Structure


A request XML packet adding a Web application to Plesk Application Vault includes the install_packages operation node:
<packet version="1.4.2.0"> <siteapp> <install_packages> ... </install_packages> </siteapp> </packet>

The install_packages node has the following graphical representation:

The filter node is required. It specifies the filtering rule. Data type: complex. The filename node is required. It specifies the full name of the Web application package file. Use the file parameter of the upload (see page 1375) operation, if you uploaded the file by POST method. Data type: string. The remove_tmp_file node is optional. It specifies if the Web application temporary files are removed after adding the package to Plesk Application Vault. Data type: none.

Supported Operations

1107

Remarks You can add multiple Web applications to Plesk Application Vault in a single packet. Add as many package_id parameters as the number of Web applications are to be added.
<filter> <package_id>...</package_id> <package_id>...</package_id> </filter>

Request Samples
Installing a single Web application This packet adds the PHPboard Web application to Plesk Application Vault and removes the PHPboard temporary files.
<packet version="1.4.2.0"> <siteapp> <install_packages> <filter> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> </filter> <remove_tmp_file/> </install_packages> </siteapp> </packet>

Installing multiple Web applications This packet adds the PHPboard, and WebTools Web applications to Plesk Application Vault.
<packet version="1.4.2.0"> <siteapp> <install_packages> <filter> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> <filename>/usr/local/psa/tmp/WebTools.rpm</filename> </filter> </install_packages> </siteapp> </packet>

1108

Supported Operations

Response Packet Structure


The install_packages node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: operationResultType (siteapp_output.xsd). The status node is required. It specifies the execution status of the install_packages operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the install_packages operation fails. Data type: integer. The errtext node is optional. It returns the error message if the install_packages operation fails. Data type: string. The filename node is required. It specifies the full name of the Web application package file. Data type: string.

Supported Operations

1109

Response Samples
Installing a single Web application This request packet adds the PHPboard Web application to Plesk Application Vault and removes the PHPboard temporary files.
<packet version="1.4.2.0"> <siteapp> <install_packages> <filter> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> </filter> <remove_tmp_file/> </install_packages> </siteapp> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <siteapp> <install_packages> <result> <status>ok</status> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> </result> </install_packages> </siteapp> </packet>

If the Web application file was not found, or if it was not a valid application package, the response from the server looks as follows:
<packet version="1.4.2.0"> <siteapp> <install_packages> <result> <status>error</status> <errcode>6008</errcode> <errtext>This file is not a valid Web application package.</errtext> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> </result> </install_packages> </siteapp> </packet>

1110

Supported Operations

Retrieving requirements for multiple Web applications

This request packet adds the PHPboard and WebTools Web applications to Plesk Application Vault.
<packet version="1.4.2.0"> <siteapp> <install_packages> <filter> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> <filename>/usr/local/psa/tmp/WebTools.rpm</filename> </filter> </install_packages> </siteapp> </packet>

If the operation succeeded, the response from the server looks as follows:
<packet version="1.4.2.0"> <siteapp> <install_packages> <result> <status>ok</status> <filename>/usr/local/psa/tmp/PHPboard.rpm</filename> </result> <result> <status>ok</status> <filename>/usr/local/psa/tmp/WebTools.rpm</filename> </result> </install_packages> </siteapp> </packet>

Supported Operations

1111

Managing Spam Filtering Service


Operator: <spamfilter> XML Schema: spamfilter.xsd Plesk version: Plesk for Unix 8.0 and later API RPC version: 1.4.2.0 Plesk user: Plesk Administrator Description The spamfilter operator manages filtering of undesirable correspondence using SpamAssassin tool in Plesk. Before using the operator, ensure the SpamAssassin is installed on the server. Plesk Administrator can enable or disable Spam Filtering service on the server. A mailbox owner can enable or disable Spam Filtering service for a specified mailbox on condition the Administrator enables manual configuration (see page 1118) of Spam Filtering service for mailbox owners. To sort incoming messages, Spam Filtering service uses black, white, unblack, and unwhite lists. Spam Filtering lists are divided into two groups: server-level lists called Administrator's lists which can be applied to all mailboxes on the server mailbox-level lists (on condition the Administrator enables this option)

For information on the lists, refer to the Types of Server Lists (see page 1116), Types of Lists Available for Mailbox Owner (see page 1116) sections. Addresses are kept in the form of templates called patterns both in black and white lists. For information on patterns, refer to the Defining Pattern (see page 1116) section.

1112

Supported Operations

Supported operations

ADD-PATTERN (see page 1119) adds a pattern to a white, black, unwhite, or unblack list DEL-PATTERN (see page 1124) removes a pattern from a white, black, unwhite, or unblack list GET-PATTERNS (see page 1130) retrieves patterns of a specified black(white), or unblack(unwhite) list GET (see page 1134) retrieves status of SpamAssassin service and Spam Filtering settings for a specified user SET (see page 1140) changes status of SpamAssassin service and Spam Filtering settings of a specified user. GET-ALLOWED-PREFERENCES (see page 1146) retrieves list of Spam Filtering settings available for a specified user GET-ALLOWED-LISTS (see page 1152) retrieves types of lists available for a specified user. CHECK (see page 1157) checks whether a Spam Filtering service is accessible

Remarks For more information on SpamAssassin application, visit http://wiki.apache.org/spamassassin/.

Supported Operations

1113

In this section:
Filtering Issues .................................................................................................. 1113 About Spam Filtering ......................................................................................... 1115 Adding Pattern .................................................................................................. 1119 Removing Pattern ............................................................................................. 1124 Retrieving Patterns ............................................................................................ 1130 Retrieving Info on Spam Filtering service .......................................................... 1134 Setting Spam Filtering Preferences ................................................................... 1140 Retrieving Available Spam Filtering Preferences ............................................... 1146 Retrieving Allowed Lists .................................................................................... 1152 Checking Status of Spam Filtering Service ........................................................ 1157

Filtering Issues
Filtering is the way the request XML packet indicates the object to which an operation will be applied. The request XML packet filters objects using a special <filter> section. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule. Note: Please, do not confuse this with Spam Filtering methods. Spam Filtering is made by the tool integrated into Plesk, and this kind of filtering is a specification of the operator.

In this section:
SpamPatternFilter Filter .................................................................................... 1113 SpamassassinFilter Filter .................................................................................. 1114 filter-id Node ...................................................................................................... 1115

SpamPatternFilter Filter
The SpamPatternFilter filter is used in add-pattern and del-pattern operations to add or remove patterns. For more information on the operations, refer to the Adding Pattern (see page 1119) and Removing Pattern (see page 1124) sections. Data type:SpamPatternFilter (spamfilter.xsd). The graphical representation of the filter node is as follows:

The pattern node is optional. It specifies template of a e-mail address. For information on patterns, refer to the Defining Pattern (see page 1116) section. Data type: string.

1114

Supported Operations

You can match multiple patterns using this filter as in the following example:
<filter> <pattern>maillist@spamme.org</pattern> <pattern>.org.ua</pattern> </filter>

Note: Use the blank filter (<filter/>) to match all patterns.

SpamassassinFilter Filter
The SpamassassinFilter filter is used in get-patterns, get , set, get-allowed-preferences, getallowed-lists operations. For more information on the operations, refer to the following sections: Retrieving Patterns (see page 1130) Retrieving Info on Spam Filtering Service (see page 1134) Setting Spam Filtering Preferences (see page 1140) Retrieving Available Spam Filtering Preferences (see page 1146) Retrieving Allowed Lists (see page 1152)

Data type:SpamassassinFilter (spamfilter.xsd). The graphical representation of the filter node is as follows:

The username node is required. It specifies a SpamAssassin user. You can specify e-mail address of a mailbox owner, or the 'admin' value. To access server settings of SpamAssassin, Plesk Administrator should set 'admin' as a value for this node. Data type: string. The spamfilter-id node is required. It specifies ID of a SpamAssassin user. Data type: integer.

You can filter by either username or spamfilter-id parameters as in the following example:
<filter> <username>my@domain.com</username> <username>admin</username> </filter>

A single operation does not support different types of parameters for a filtering rule, so the following filter will be considered invalid by Plesk:
<filter> <username>my@domain.com</username> <spamfilter-id>admin</spamfilter-id> </filter>

Supported Operations

1115

filter-id Node

If an operation uses filters in a request packet, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule, it is returned in the filter-id node of the response packet. Address of a mailbox owner, or string 'admin' ID of a SpamAssassin user Pattern

It is done to trace the request parameters in case of an error. Data type: anySimple. All operations except for the check possess the filter-id node in the response packet.

About Spam Filtering


This section consists of the following subsections: Defining Pattern. Explains what a pattern is, and what patterns are valid in SpamAssassin. Scoring Messages. Describes what the scoring of messages is, and why it is needed. Types of Server Lists. Tells about black and white lists managed by Plesk Administrator. Types of Lists Available for Mailbox Owner. Tells about black, white, unblack, and unwhite lists managed by mailbox owners. Spam Filtering Preferences. Describes Spam Filtering preferences available for mailbox owners and Administrator.

In this section:
Defining Pattern .................................................................................................1116 Scoring Messages .............................................................................................1116 Types of Server Lists .........................................................................................1116 Types of Lists Available for Mailbox Owners ......................................................1116 Spam Filtering Preferences................................................................................1118

1116

Supported Operations

Defining Pattern
Addresses are kept in the form of templates called patterns both in black and white lists. A valid pattern can be formatted as <domain> or <e-mail>@<domain>, where <domain> is a series of labels glued with '.' (dot) characters. The allowed formats for the domain part are ASCII and IDN. You can use an asterisk (*) as a substitute for a number of letters, and question mark (?) as a substitute for a single letter. For example: address@spammers.net, user?@spammers.net, *@spammers.net. Specifying *@spammers.net will block the entire mail domain spammers.net.

Scoring Messages
Spam Filtering service performs a number of different tests on contents and subject line of each message. As a result, each message scores a number of points. The higher the number, the more likely a message is spam. For example, a message containing the text string "BUY VIAGRA AT LOW PRICE!!!" in Subject line and message body scores 8.3 points. By default, the filter sensitivity is set so that all messages that score 7 or more points are classified as spam.

Types of Server Lists


There are two kinds of server lists Black list contains addresses all correspondence from which will be marked as spam. White list contains addresses all correspondence from which will be received ignoring Spam Filtering rules.

These lists belong to Plesk Administrator (SpamAssassin specifies Administrator by admin username). Note: Incoming messages processed according to server lists and marked as spam are not removed from the server.

Types of Lists Available for Mailbox Owners


If Spam Filtering settings for mailbox owners are enabled by Administrator, a mailbox owner can manage his own black, white, unblack, and unwhite lists. Black list contains addresses all correspondence from which will be marked as spam. White list contains addresses all correspondence from which will be received ignoring Spam Filtering rules. Note: A mailbox owner should enable reject-spam option to remove spam messages. For information on this option, refer to the Spam Filtering Preferences (see page 1118) section.

Supported Operations

1117

By default, black (white) lists of mailbox owners are blank. In Plesk for Unix, Spam Filtering is performed according to server lists (it means server wide settings are used) by default. To receive messages from addresses that are found in server black list without a spam mark, a mailbox owner should add them to unblack list. If messages from addresses found in server white list are considered requiring spam filtering, the addresses should be added to unwhite list. In Plesk for Windows, users can turn off Spam Filtering according to server settings and filter incoming messages using only their own black (white) lists. For information on how to change Spam filtering method, refer to the Spam Filtering Preferences (see page 1118) section. Note: If Spam Filtering is done using server and personal settings, you need to unify server list (without un-list patterns defined by user) and a list of a mailbox owner to retrieve all Spam Filtering patterns. The set forth below example helps to clarify how do lists of a mailbox owner form. The following table shows possible server patterns: Server lists
Black list *@spam.net *.fastmail.net great@subscription.org White list essential@customer.com

The following table shows possible patterns of a mailbox owner: Mailbox owner's lists
Black list hate@myspam.org Unblack list great@subscription.or g Unwhite list White list essential@customer.co orders@domain.com m

If the Spam Filtering for the mailbox owner is done according to server and personal Spam Filtering settings, the patterns lists for the user look as follows: Mailbox owner's lists
Patterns for e-mails that are considered to be spam *@spam.net *.fastmail.net hate@myspam.org Patterns for trusted e-mails orders@domain.com

1118

Supported Operations

Spam Filtering Preferences


Spam Filtering preferences can be divided into three groups: preferences for Plesk Administrator (can also be called server preferences), mailbox owner, and common preferences. The preferences node is presented by type SpamassassinPreferencesType (spamfilter.xsd). This node has the following graphics representation:

Preferences available only for Plesk Administrator: The personal node is optional. If set to true, it allows mailbox owners to specify their own Spam Filtering preferences. Data type: boolean. The max-children-process node is optional. It specifies the maximum number of filtering processes to run simultaneously. The quality of filtering depends on this number (the best quality equals 5 ). Data type: integer. Allowed values: 1 | 2 | 3 | 4 | 5. Default value: 5.

Preferences available only for a mailbox owner: The reject-spam node is optional. It specifies if spam messages will be deleted when they come to a mailbox. Data type: boolean.

Preferences available both for Plesk Administrator and for mailbox owner: The use-server-wide-settings node is optional. It specifies if the server Spam Filtering settings are applied to incoming messages of mailbox owners. For more information on the settings, refer to the Types of Lists Available for Mailbox Owners (see page 1116) section. Data type: boolean. Note: This node is not supported by Plesk for Unix. You cannot retrieve or update value for this node. By default it is 1.

Supported Operations

1119

The required-score node is optional. It specifies the number of points a message should gain to be considered to be spam. For information on scoring messages, refer to the Scoring Messages (see page 1116) section. Data type: anySimpleType. Default value: 7. The rewrite-header node is optional. It specifies the text that will be added to the beginning of subject of each message recognized as spam. To add a message's score, set the _SCORE_ value for this node. For information on message scoring, refer to the Scoring Messages (see page 1116) section. Data type: string.

Spam Filtering preferences set of a mailbox owner can look as follows:


<preferences> <required-score>7</required-score> <reject-spam>1</reject-spam> <rewrite-header/> </preferences>

Adding Pattern
Use the add-pattern operation to add new patterns to a specified list of a specified user (Administrator or mailbox owner). For information on patterns refer to the Defining Pattern (see page 1116) section.

In this section:
Request Packet Structure.................................................................................. 1119 Request Samples .............................................................................................. 1121 Response Packet Structure ............................................................................... 1122 Response Samples ........................................................................................... 1123

Request Packet Structure


A request XML packet adding a pattern includes the add-pattern operation node:
<packet version="1.4.2.0"> <spamfilter> <add-pattern> ... </add-pattern> </spamfilter> </packet>

1120

Supported Operations

The add-pattern node is presented by the SpamFilterAddPatternInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: SpamPatternFilter (spamfilter.xsd). The list node is required. It specifies the type of the list. For information on list types, refer to the Types of Server Lists (see page 1116) and Types of Lists available for Mailbox Owners (see page 1116) sections. Data type: SpamListType (spamfilter.xsd). Allowed values: black | white | unblack | unwhite. The username node is required.It specifies the name of a SpamAssassin user. You can specify e-mail address of a mailbox owner, or the 'admin' value. To access server black (white) lists, you should set 'admin' as a value for this node. Data type: string. The spamfilter-id node is required. It specifies the ID of a SpamAssassin user. Data type: integer.

Remarks You can add patterns to multiple users in a single packet. Add as many add-pattern operations as the number of different users to be affected.
<add-pattern> </add-pattern> <add-pattern> </add-pattern>

Supported Operations

1121

Request Samples
Adding a pattern This packet adds pattern *@spam.net to the server black list.
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <filter> <pattern>*@spam.net</pattern> </filter> <list>black</list> <username>admin</username> </add-pattern> </spamfilter> </packet>

Adding multiple patterns This packet adds patterns *@spam.net and spam@mailme.net to the black list of mailbox mybox@domain.com.
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>black</list> <username>mybox@domain.com</username> </add-pattern> </spamfilter> </packet>

This packet adds patterns *@spam.net and spam@mailme.net to the unblack list of mailbox mybox@domain.com, and to the server black list. It means mybox@domain.com will receive e-mail messages from addresses defined by patterns, although the server will consider these messages to be spam.
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>black</list> <username>admin</username> </add-pattern> <add-pattern>

1122

Supported Operations <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>unblack</list> <username>mybox@domain.com</username> </add-pattern> </spamfilter> </packet>

Response Packet Structure


The add-pattern node of the output XML packet is presented by type SpamFilterAddPatternOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the add-pattern operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the add-pattern operation fails. Data type: integer. The errtext node is optional. It returns the error message if the add-pattern operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimple. The id node is optional. It returns the ID of the added pattern if the operation succeeds. Data type: integer.

Supported Operations

1123

Response Samples
Adding a pattern This request packet adds pattern *@spam.net to the server black list.
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <filter> <pattern>*@spam.net</pattern> </filter> <list>black</list> <username>admin</username> </add-pattern> </spamfilter> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <spamfilter> <add-pattern> <result> <status>ok</status> <filter-id>*@spam.net</filter> <id>17</id> </result> </add-pattern> </spamfilter> </packet>

If the SpamAssassin service is restricted by Plesk license key, or a user does not have access to SpamAssassin management, the response is as follows:
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <result> <status>error</status> <errcode>1006</errcode> <errtext>Permission denied.</errtext> <filter-id>*@spam.net</filter> </result> </add-pattern> </spamfilter> </packet>

1124

Supported Operations

Adding multiple patterns This request packet adds patterns *@spam.net and spam@mailme.net to the black list of mailbox mybox@domain.com.
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>black</list> <username>mybox@domain.com</username> </add-pattern> </spamfilter> </packet>

If the pattern *@spam.net is already present in the black list of the mailbox owner, the response can look as follows:
<packet version="1.4.2.0"> <spamfilter> <add-pattern> <result> <status>error</status> <errcode>1007</errcode> <errtext>The inserted data already exists.</errtext> <filter-id>*@spam.net</filter> </result> <result> <status>ok</status> <filter-id>spam@mailme.net</filter> <id>15</id> </result> </add-pattern> </spamfilter> </packet>

Supported Operations

1125

Removing Pattern
Use the del-pattern operation to remove patterns from a specified list of a specified user (Administrator or mailbox owner). For information on patterns refer to the Defining Pattern (see page 1116) section.

In this section:
Request Packet Structure.................................................................................. 1125 Request Samples .............................................................................................. 1126 Response Packet Structure ............................................................................... 1127 Response Samples ........................................................................................... 1128

Request Packet Structure


A request XML packet removing a pattern includes the del-pattern operation node:
<packet version="1.4.2.0"> <spamfilter> <del-pattern> ... </del-pattern> </spamfilter> </packet>

The del-pattern node is presented by the SpamFilterDelPatternInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: SpamPatternFilter (spamfilter.xsd). The list node is required. It specifies the type of the list. For information on list types, refer to the Types of Server Lists (see page 1116) and Types of Lists available for Mailbox Owners (see page 1116) sections. Data type: SpamListType (spamfilter.xsd). Allowed values: black | white | unblack | unwhite. The username node is required.It specifies the name of a SpamAssassin user. You can specify e-mail address of a mailbox owner, or the admin value. To access server black (white) lists , you should set admin as a value for this node. Data type: string.

1126

Supported Operations

The spamfilter-id node is required. It specifies the ID of a SpamAssassin user. Data type: integer.

Remarks You can remove patterns from multiple users in a single packet. Add as many delpattern operations as the number of different users to be affected.
<del-pattern> </del-pattern> <del-pattern> </del-pattern>

Request Samples
Removing a pattern This packet removes pattern *@spam.net from the server black list.
<packet version="1.4.2.0"> <spamfilter> <del-pattern> <filter> <pattern>*@spam.net</pattern> </filter> <list>black</list> <username>admin</username> </del-pattern> </spamfilter> </packet>

Removing multiple patterns This packet removes patterns *@spam.net and spam@mailme.net from the black list of mailbox mybox@domain.com.
<packet version="1.4.2.0"> <spamfilter> <del-pattern> <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>black</list> <username>mybox@domain.com</username> </del-pattern> </spamfilter> </packet>

Supported Operations

1127

This packet removes patterns *@spam.net and spam@mailme.net from the black list of mailbox mybox@domain.com, and from server black list.
<packet version="1.4.2.0"> <spamfilter> <del-pattern> <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>black</list> <username>mybox@domain.com</username> </del-pattern> <del-pattern> <filter> <pattern>*@spam.net</pattern> <pattern>spam@mailme.net</pattern> </filter> <list>black</list> <username>admin</username> </del-pattern> </spamfilter> </packet>

Response Packet Structure


The del-pattern node of the output XML packet is presented by type SpamFilterDelPatternOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd).

1128

Supported Operations

The status node is required. It specifies the execution status of the del-pattern operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the del-pattern operation fails. Data type: integer. The errtext node is optional. It returns the error message if the del-pattern operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimple. The id node is optional. It returns the ID of the removed pattern if the operation succeeds. Data type: integer.

Response Samples
Removing a pattern This request packet removes pattern *@spam.net from the server black list.
<packet version="1.4.2.0"> <spamfilter> <del-pattern> <filter> <pattern>*@spam.net</pattern> </filter> <list>black</list> <username>admin</username> </del-pattern> </spamfilter> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <spamfilter> <del-pattern> <result> <status>ok</status> <filter-id>*@spam.net</filter> <id>17</id> </result> </del-pattern> </spamfilter> </packet>

Supported Operations

1129

If the SpamAssassin service was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <spamfilter> <del-pattern> <result> <status>error</status> <errcode>1026</errcode> <errtext>Component is not installed.</errtext> <filter-id>*@spam.net</filter> </result> </del-pattern> </spamfilter> </packet>

Removing multiple patterns This request packet removes pattern *@spam.net from the black list of mailbox mybox@domain.com, and server black list.
<packet version="1.4.2.0"> <spamfilter> <del-pattern> <filter> <pattern>*@spam.net</pattern> </filter> <list>black</list> <username>mybox@domain.com</username> </del-pattern> <del-pattern> <filter> <pattern>*@spam.net</pattern> </filter> <list>black</list> <username>admin</username> </del-pattern> </spamfilter> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <spamfilter> <del-pattern> <result> <status>ok</status> <filter-id>*@spam.net</filter> <id>17</id> </result> </del-pattern> <del-pattern> <result> <status>ok</status> <filter-id>*@spam.net</filter> <id>1</id> </result> </del-pattern> </spamfilter> </packet>

1130

Supported Operations

Retrieving Patterns
Use the get-patterns operation to retrieve patterns from a specified list of a specified user (Administrator or mailbox owner).

In this section:
Request Packet Structure.................................................................................. 1130 Request Samples .............................................................................................. 1131 Response Packet Structure ............................................................................... 1132 Response Samples ........................................................................................... 1133

Request Packet Structure


A request XML packet retrieving a pattern includes the get-patterns operation node:
<packet version="1.4.2.0"> <spamfilter> <get-patterns> ... </get-patterns> </spamfilter> </packet>

The get-patterns node is presented by the SpamFilterGetPatternsInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is optional. It specifies the filtering rule. Data type: SpamassassinFilterType (spamfilter.xsd). The list node is required. It specifies the type of the list. For information on list types, refer to the Types of Server Lists (see page 1116) and Types of Lists available for Mailbox Owners (see page 1116) sections. Data type: SpamListType (spamfilter.xsd). Allowed values: black | white | unblack | unwhite.

Supported Operations

1131

Remarks You can retrieve multiple lists for users specified by different filtering rules in a single packet. Add as many get-patterns operations as the number of different filtering rules to be applied.
<get-patterns> </get-patterns> <get-patterns> </get-patterns>

Request Samples
Retrieving patterns from a single list This packet retrieves patterns from server white list.
<packet version="1.4.2.0"> <spamfilter> <get-patterns> <filter> <username>admin</username> </filter> <list>white</list> </get-patterns> </spamfilter> </packet>

Retrieving patterns from multiple lists This packet retrieves patterns from unwhite list of mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get-patterns> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> <list>unwhite</list> </get-patterns> </spamfilter> </packet>

1132

Supported Operations

This packet retrieves patterns from unwhite list of mailboxes mybox@domain.com and my@domain.com, and from server white list.
<packet version="1.4.2.0"> <spamfilter> <get-patterns> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> <list>unwhite</list> </get-patterns> <get-patterns> <filter> <username>admin</username> </filter> <list>white</list> </get-patterns> </spamfilter> </packet>

Response Packet Structure


The get-patterns node of the output XML packet is presented by type SpamFilterGetPatternsOutputType (spamfilter.xsd) and structured as follows:

Supported Operations

1133

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-patterns operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-patterns operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-patterns operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimpleType. The id node is optional. It returns the ID of the Spamassassin user, if the operation succeeds. Data type: integer. The pattern node is optional. It holds a pattern of the specified list. Data type: string.

Remarks If a list contains more than one pattern, the set of patterns will look as follows: <pattern>...</pattern>...<pattern>...</pattern>. For more information, refer to the Response Samples (see page 1133) section.

Response Samples
Retrieving patterns from a single list This request packet retrieves patterns from server white list.
<packet version="1.4.2.0"> <spamfilter> <get-patterns> <filter> <username>admin</username> </filter> <list>white</list> </get-patterns> </spamfilter> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <spamfilter> <get-patterns> <result> <status>ok</status> <filter-id>admin</filter-id> <id>1</id> <pattern>*@spam.net</pattern> <pattern>maillist@subscribespam.net</pattern> <pattern>*.ua</pattern> </result> </get-patterns> </spamfilter> </packet>

1134

Supported Operations

Retrieving patterns from multiple lists This request packet retrieves patterns from unwhite list of mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get-patterns> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> <list>unwhite</list> </get-patterns> </spamfilter> </packet>

If user my@domain.com was not found on the server, the result is as follows:
<packet version="1.4.2.0"> <spamfilter> <get-patterns> <result> <status>ok</status> <filter-id>admin</filter-id> <id>16</id> <pattern>*.ua</pattern> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>User does not exist.</errtext> <filter-id>my@domain.com</filter> </result> </get-patterns> </spamfilter> </packet>

Retrieving Info on Spam Filtering service


Use the get operation to retrieve status of Spam Filtering service, and Spam Filtering preferences for a specified user (Administrator or mailbox owner).

In this section:
Request Packet Structure.................................................................................. 1135 Request Samples .............................................................................................. 1136 Response Packet Structure ............................................................................... 1137 Response Samples ........................................................................................... 1138

Supported Operations

1135

Request Packet Structure


A request XML packet retrieving info on Spam Filtering service includes the get operation node:
<packet version="1.4.2.0"> <spamfilter> <get> ... </get> </spamfilter> </packet>

The get node is presented by the SpamFilterGetInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: SpamassassinFilterType (spamfilter.xsd).

Remarks You can retrieve info on users specified by SpamAssassin ID, and users specified by e-mail address in a single packet. Add ID's of users specified by SpamAssassin ID to the filter node of the first get operation, and e-mail addresses of users specified by email address (or string admin) to the filter node of the second get operation.
<get> <filter> ... </filter> </get> <get> <filter> ... </filter> </get>

1136

Supported Operations

Request Samples
Retrieving info on a single user This packet retrieves configuration of Spam Filtering service for Administrator (server).
<packet version="1.4.2.0"> <spamfilter> <get> <filter> <username>admin</username> </filter> </get> </spamfilter> </packet>

Retrieving info on multiple users This packet retrieves configuration of Spam Filtering service for mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> </get> </spamfilter> </packet>

This packet retrieves configuration of Spam Filtering service for mailbox mybox@domain.com, and the SpamAssassin user with ID 7.
<packet version="1.4.2.0"> <spamfilter> <get> <filter> <username>mybox@domain.com</username> </filter> </get> <get> <filter> <spamfilter-id>7</spamfilter-id> </filter> </get> </spamfilter> </packet>

Supported Operations

1137

Response Packet Structure


The get node of the output XML packet is presented by type SpamFilterGetOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimpleType. The id node is optional. It returns the ID of the Spamassassin user if the operation succeeds. Data type: integer. The following nodes are nested in the response packet only if the operation succeeds:

1138

Supported Operations

The username node is optional. It holds the e-mail address of SpamAssassin user, or string 'admin'. Data type: string. The enabled node is optional. It specifies if the Spam Filtering service is enabled for a specified SpamAssassin user. For more information, refer to the Managing Spam Filtering (see page 1111) section. Data type: none. The disabled node is optional. It specifies if the Spam Filtering service is disabled for a specified SpamAssassin user. For more information, refer to the Managing Spam Filtering (see page 1111) section. Data type: none. The preferences node is optional. It specifies preferences of Spam Filtering service for a specified user. For information on preferences, refer to the Spam Filtering Preferences (see page 1118) section. Data type: SpamassassinPreferencesType (spamfilter.xsd).

Response Samples
Retrieving info on a single user This request packet retrieves configuration of Spam Filtering service for Administrator (server).
<packet version="1.4.2.0"> <spamfilter> <get> <filter> <username>admin</username> </filter> </get> </spamfilter> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <spamfilter> <get> <result> <status>ok</status> <filter-id>admin</filter-id> <id>1</id> <username>admin</username> <enabled/> <preferences> <personal>1</personal> <max-children-process>5</max-children-process> <required-store>7</required-store> <rewrite-header/> </preferences> </result> </get> </spamfilter> </packet>

Supported Operations

1139

If the SpamAssassin service was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <spamfilter> <get> <result> <status>error</status> <errcode>1026</errcode> <errtext>Component is not installed.</errtext> <filter-id>admin</filter> </result> </get> </spamfilter> </packet>

Retrieving info on multiple users This request packet retrieves configuration of Spam Filtering service for mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> </get> </spamfilter> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <spamfilter> <get> <result> <status>ok</status> <filter-id>mybox@domain.com</filter-id> <id>11</id> <username>mybox@domain.com</username> <enabled/> <preferences> <reject-spam>1</reject-spam> <required-store>7</required-store> <rewrite-header/> </preferences> </result> <result> <status>ok</status> <filter-id>my@domain.com</filter-id> <id>12</id> <username>my@domain.com</username> <disabled/>

1140

Supported Operations <preferences> <reject-spam>0</reject-spam> <required-store>7</required-store> <rewrite-header>_SCORE_</rewrite-header> </preferences> </result> </get> </spamfilter> </packet>

Setting Spam Filtering Preferences


Use the set operation to change status of Spam Filtering service, and Spam Filtering preferences for a specified user (Administrator or mailbox owner).

In this section:
Request Packet Structure.................................................................................. 1140 Request Samples .............................................................................................. 1141 Response Packet Structure ............................................................................... 1143 Response Samples ........................................................................................... 1144

Request Packet Structure


A request XML packet changing Spam Filtering service status and preferences includes the set operation node:
<packet version="1.4.2.0"> <spamfilter> <set> ... </set> </spamfilter> </packet>

The set node is presented by the SpamFilterGetInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: SpamassassinFilterType (spamfilter.xsd).

Supported Operations

1141

The preferences node is required. It specifies preferences of Spam Filtering service for a specified user. For information on preferences, refer to the Spam Filtering Preferences (see page 1118) section. Data type:SpamassassinPreferencesType (spamfilter.xsd). Note: If you want to enable or disable Spam Filtering service without changing preferences, leave the preferences node blank (<preferences/>).

The enabled node is optional. Specify this node to enable Spam Filtering service for a specified SpamAssassin user. For more information, refer to the Managing Spam Filtering (see page 1111) section. Data type: none. The disabled node is optional. Specify this node to disable Spam Filtering service for a specified SpamAssassin user. For more information, refer to the Managing Spam Filtering (see page 1111) section. Data type: none.

Remarks You can retrieve info on users specified by SpamAssassin ID, and users specified by e-mail address in a single packet. Add ID's of users specified by SpamAssassin ID to the filter node of the first set operation, and e-mail addresses of users specified by email address (or 'admin' string) to the filter node of the second set operation.
<set> <filter>...</filter> </set> <set> <filter>...</filter> </set>

Request Samples
Changing info of a single user This request packet enables Spam Filtering service on the server.
<packet version="1.4.2.0"> <spamfilter> <set> <filter> <username>admin</username> </filter> <preferences/> <enabled/> </set> </spamfilter> </packet>

1142

Supported Operations

Changing info for multiple users This packet requests for deleting incoming spam coming to mailboxes my@account.com and mail@account.com. It also enables Spam Filtering service on the mailboxes.
<packet version="1.4.2.0"> <spamfilter> <set> <filter> <username>my@account.com</username> <username>mail@account.com</username> </filter> <preferences> <reject-spam>1</reject-spam> </preferences> <enabled/> </set> </spamfilter> </packet>

This packet requests for adding '***SPAM***' to subject of spam messages sent to mailbox mybox@domain.com. It also disables Spam Filtering service for the SpamAssassin user specified by ID 7.
<packet version="1.4.2.0"> <spamfilter> <set> <filter> <username>mybox@domain.com</username> </filter> <preferences> <rewrite-header>***SPAM***</rewrite-header> </preferences> </set> <set> <filter> <spamfilter-id>7</spamfilter-id> </filter> <disabled/> </set> </spamfilter> </packet>

Supported Operations

1143

Response Packet Structure


The set node of the output XML packet is presented by type SpamFilterSetOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the set operation fails. Data type: integer. The errtext node is optional. It returns the error message if the set operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimpleType. The id node is optional. It does not return any data for this operation. Data type: integer.

1144

Supported Operations

Response Samples
Changing info of a single user This request packet enables Spam Filtering service on the server.
<packet version="1.4.2.0"> <spamfilter> <set> <filter> <username>admin</username> </filter> <preferences/> <enabled/> </set> </spamfilter> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <spamfilter> <set> <result> <status>ok</status> <filter-id>admin</filter-id> </result> </set> </spamfilter> </packet>

If inappropriate options for Administrator were nested in the parameters node of the request packet, the response from the server is as follows:
<packet version="1.4.2.0"> <spamfilter> <set> <result> <status>error</status> <errcode>12009</errcode> <errtext>Option is not supported</errtext> <filter-id>admin</filter-id> </result> </set> </spamfilter> </packet>

Supported Operations

1145

Changing info for multiple users This packet requests for deleting incoming spam coming to mailboxes my@account.com and mail@account.com. It also enables Spam Filtering service on the mailbox specified by SpamAssassin ID 12.
<packet version="1.4.2.0"> <spamfilter> <set> <filter> <username>my@account.com</username> <username>mail@account.com</username> </filter> <preferences> <reject-spam>1</reject-spam> </preferences> <enabled/> </set> <set> <filter> <spamfilter-id>my@account.com</spamfilter-id> </filter> <preferences/> <enabled/> </set> </spamfilter> </packet>

If mailbox mail@account.com was not found on the server, a response from the server can look as follows:
<packet version="1.4.2.0"> <spamfilter> <set> <result> <status>ok</status> <filter-id>my@account.com</filter-id> </result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Mailbox does not exist</errtext> <filter-id>mail@account.com</filter-id> </result> </set> <set> <result> <status>ok</status> <filter-id>12</filter-id> </result> </set> </spamfilter> </packet>

1146

Supported Operations

Retrieving Available Spam Filtering Preferences


Use the get-allowed-preferences operation to retrieve Spam Filtering preferences available for a specified user (mailbox owner or Administrator). For information on Spam Filtering preferences available for a specified user, refer to the Spam Filtering Preferences (see page 1118) section.

In this section:
Request Packet Structure.................................................................................. 1146 Request Samples .............................................................................................. 1147 Response Packet Structure ............................................................................... 1148 Response Samples ........................................................................................... 1149

Request Packet Structure


A request XML packet retrieving available Spam Filtering preferences includes the getallowed-preferences operation node:
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> ... </get-allowed-preferences> </spamfilter> </packet>

The get-allowed-preferences node is presented by the SpamFilterGetAllowedPreferencesInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: SpamassassinFilterType (spamfilter.xsd).

Supported Operations

1147

Remarks You can retrieve info on users specified by SpamAssassin ID, and users specified by e-mail address in a single packet. Add ID's of users specified by SpamAssassin ID to the filter node of the first get-allowed-preferences operation, and e-mail addresses of users specified by e-mail address (or 'admin' string) to the filter node of the second getallowed-preferences operation.
<get-allowed-preferences> <filter> ... </filter> </get-allowed-preferences> <get-allowed-preferences> <filter> ... </filter> </get-allowed-preferences>

Request Samples
Retrieving Spam Filtering preferences available for a single user This packet retrieves info on Spam Filtering preferences available for Administrator (server preferences).
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>admin</username> </filter> </get-allowed-preferences> </spamfilter> </packet>

Retrieving Spam Filtering preferences available for multiple users This packet retrieves Spam Filtering preferences available for mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> </get-allowed-preferences> </spamfilter> </packet>

1148

Supported Operations

This packet retrieves Spam Filtering preferences available for mailboxes mybox@domain.com, and user specified by SpamAssassin ID 7.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>mybox@domain.com</username> </filter> </get-allowed-preferences> <get-allowed-preferences> <filter> <spamfilter-id>7</spamfilter-id> </filter> </get-allowed-preferences> </spamfilter> </packet>

Response Packet Structure


The get-allowed-preferences node of the output XML packet is presented by type SpamFilterGetAllowedPreferencesOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-allowedpreferences operation. Data type: string. Allowed values: ok | error.

Supported Operations

1149

The errcode node is optional. Is returns the error code if the get-allowed-preferences operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-allowed-preferences operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameter. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimpleType. The id node is optional. It does not return any data for this operation. Data type: integer. The preference node is optional. It holds Spam Filtering preferences available for the specified SpamAssassin user. Data type: string.

Note: preferences are separated by the <preference> tag.

Response Samples
Retrieving Spam Filtering preferences available for a single user This request packet retrieves Spam Filtering service preferences available for Administrator.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>admin</username> </filter> </get-allowed-preferences> </spamfilter> </packet>

A positive response from the server looks as follows:


<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <result> <status>ok</status> <filter-id>admin</filter-id> <preference>personal</preference> <preference>max-children-process</preference> <preference>required-score</preference> <preference>rewrite-header</preference> </result> </get-allowed-preferences> </spamfilter> </packet>

1150

Supported Operations

If the SpamAssassin service is restricted by Plesk licence key, or a user does not have access to SpamAssassin management, the response is as follows:

<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <result> <status>error</status> <errcode>1006</errcode> <errtext>Permission denied.</errtext> <filter-id>admin</filter> </result> </get-allowed-preferences> </spamfilter> </packet>

Retrieving Spam Filtering preferences available for multiple users This request packet retrieves Spam Filtering preferences available for mailbox mybox@domain.com, and SpamAssassin user with ID 7.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>mybox@domain.com</username> </filter> </get-allowed-preferences> <get-allowed-preferences> <filter> <spamfilter-id>7</spamfilter-id> </filter> </get-allowed-preferences> </spamfilter> </packet>

Supported Operations

1151

A positive response from the server looks as follows:


<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <result> <status>ok</status> <filter-id>mybox@domain.com</filter-id> <preference>personal</preference> <preference>max-children-process</preference> <preference>required-score</preference> <preference>rewrite-header</preference> </result> </get-allowed-preferences> <get-allowed-preferences> <result> <status>ok</status> <filter-id>7</filter-id> <preference>reject-spam</preference> <preference>required-score</preference> <preference>rewrite-header</preference> </result> </get-allowed-preferences> </spamfilter> </packet>

This request packet retrieves Spam Filtering preferences available for mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> </get-allowed-preferences> </spamfilter> </packet>

1152

Supported Operations

A positive response from the server looks as follows:


<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <result> <status>ok</status> <filter-id>mybox@domain.com</filter-id> <preference>personal</preference> <preference>max-children-process</preference> <preference>required-score</preference> <preference>rewrite-header</preference> </result> <result> <status>ok</status> <filter-id>my@domain.com</filter-id> <preference>reject-spam</preference> <preference>required-score</preference> <preference>rewrite-header</preference> </result> </get-allowed-preferences> </spamfilter> </packet>

Retrieving Allowed Lists


Use the get-allowed-lists operation to types of lists available for a specified user (mailbox owner or Administrator). For information on types of lists, refer to the Types of Server List (see page 1116) and Types of Lists Available for Mailbox Owner (see page 1116) sections.

In this section:
Request Packet Structure.................................................................................. 1153 Request Samples .............................................................................................. 1154 Response Packet Structure ............................................................................... 1155 Response Samples ........................................................................................... 1156

Supported Operations

1153

Request Packet Structure


A request XML packet retrieving available types of lists includes the get-allowed-lists operation node:
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> ... </get-allowed-lists> </spamfilter> </packet>

The get-allowed-lists node is presented by the SpamFilterGetAllowedListsInputType type (spamfilter.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. Data type: SpamassassinFilterType (spamfilter.xsd).

Remarks You can retrieve info on users specified by SpamAssassin ID, and users specified by e-mail address in a single packet. Add ID's of users specified by SpamAssassin ID to the filter node of the first get-allowed-lists operation, and e-mail addresses of users specified by e-mail address (or 'admin' string) to the filter node of the second getallowed-lists operation.
<get-allowed-lists> <filter> ... </filter> </get-allowed-lists> <get-allowed-lists> <filter> ... </filter> </get-allowed-lists>

1154

Supported Operations

Request Samples
Retrieving types of lists available for a single user This packet retrieves available types of server lists (Administrator's lists).
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <filter> <username>admin</username> </filter> </get-allowed-lists> </spamfilter> </packet>

Retrieving types of lists available for multiple users This packet retrieves types of lists available for mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> </get-allowed-lists> </spamfilter> </packet>

This packet retrieves types of lists available for mailboxes mybox@domain.com, and SpamAssassin user with ID 7.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-preferences> <filter> <username>mybox@domain.com</username> </filter> </get-allowed-preferences> <get-allowed-preferences> <filter> <spamfilter-id>7</spamfilter-id> </filter> </get-allowed-preferences> </spamfilter> </packet>

Supported Operations

1155

Response Packet Structure


The get-allowed-lists node of the output XML packet is presented by type SpamFilterGetAllowedListsOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-allowed-lists operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-allowed-lists operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-allowed-lists operation fails. Data type: string. The filter-id node is optional. It holds the filtering rule parameters. For information, refer to the Filtering Issues (see page 1115) section. Data type: anySimpleType. The id node is optional. It does not return any data for this operation. Data type: integer. The list node is optional. It holds types of lists available for the specified SpamAssassin user. Data type: string.

Note: list types are separated by the <list> tag.

1156

Supported Operations

Response Samples
Retrieving types of lists available for a single user This request packet retrieves available types of server lists.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <filter> <username>admin</username> </filter> </get-allowed-lists> </spamfilter> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <result> <status>ok</status> <filter-id>admin</filter-id> <list>black</list> <list>white</list> </result> </get-allowed-lists> </spamfilter> </packet>

If the SpamAssassin service was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <result> <status>error</status> <errcode>1026</errcode> <errtext>Component is not installed.</errtext> <filter-id>admin</filter> </result> </get-allowed-lists> </spamfilter> </packet>

Supported Operations

1157

Retrieving types of lists available for multiple users This packet retrieves types of lists available for mailboxes mybox@domain.com and my@domain.com.
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <filter> <username>mybox@domain.com</username> <username>my@domain.com</username> </filter> </get-allowed-lists> </spamfilter> </packet>

If mailbox mybox@domain.com was not found on the server, the response looks as follows:
<packet version="1.4.2.0"> <spamfilter> <get-allowed-lists> <result> <status>error</status> <errcode>1013</errcode> <errtext>Mailbox does not exist.</errtext> <filter-id>mybox@domain.com</filter> </result> <result> <status>ok</status> <filter-id>my@domain.com</filter-id> <list>black</list> <list>white</list> <list>unblack</list> <list>unwhite</list> </result> </get-allowed-lists> </spamfilter> </packet>

1158

Supported Operations

Checking Status of Spam Filtering Service


Use the check operation to check if the Spam Filtering service is installed on the server and allowed by Plesk license.

In this section:
Request Packet ................................................................................................. 1158 Response Packet Structure ............................................................................... 1159 Response Samples ........................................................................................... 1160

Request Packet
A request XML packet retrieving status of Spam Filtering service on the server includes the check operation node:
<packet version="1.4.2.0"> <spamfilter> <check/> </spamfilter> </packet>

The check node graphical representation is as follows:

Request packet sample The packet retrieving status of Spam Filtering service looks as follows:
<packet version="1.4.2.0"> <spamfilter> <check/> </spamfilter> </packet>

Supported Operations

1159

Response Packet Structure


The check node of the output XML packet is presented by type SpamFilterCheckOutputType (spamfilter.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies if the Spam Filtering service is installed on the server and allowed by Plesk license. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the check operation fails. Data type: integer. The errtext node is optional. It returns the error message if the check operation fails. Data type: string.

1160

Supported Operations

Response Samples
Request packet sample The packet retrieving status of Spam Filtering service looks as follows:
<packet version="1.4.2.0"> <spamfilter> <check/> </spamfilter> </packet>

A positive response from the server looks as follows:


<packet version="1.4.2.0"> <spamfilter> <check> <status>ok</status> </check> </spamfilter> </packet>

If the SpamAssassin service is restricted by Plesk licence key, or a user does not have access to SpamAssassin management, the response is as follows:
<packet version="1.4.2.0"> <spamfilter> <check> <result> <status>error</status> <errcode>1006</errcode> <errtext>Permission denied.</errtext> </result> </check> </spamfilter> </packet>

If the SpamAssassin service was not found on the server, the response is as follows:
<packet version="1.4.2.0"> <spamfilter> <check> <result> <status>error</status> <errcode>1026</errcode> <errtext>Component is not installed.</errtext> </result> </check> </spamfilter> </packet>

Supported Operations

1161

Managing SSL Certificates


Operator: <certificate> XML Schema: certificate_input.xsd, certificate_output.xsd Plesk version: Plesk 7.5.3 for Unix and later, Plesk 7.6 for Windows API RPC version: 1.3.5.0 and higher Plesk user: Plesk Administrator Description Using the Secure Sockets Layer protocol on a domain requires an SSL certificate installed first. This can be a certificate purchased from a certificate vendor or a selfsigned certificate generated on your own. Plesk supports two-levels certificate repository: The bottom level is constituted by separate domain repositories. Certificates installed to a domain repository can be used on this domain or on any domain belonging to the same client account. The upper level is Administrator's repository. Certificates installed to the Administrator's repository can be used on any domain existing in Plesk. One of these certificates can be defined as default, meaning that it is used for accessing Plesk GUI via the HTTPs protocol.

Supported operations

INSTALL (see page 1162) installs an SSL certificate to either Administrator's or specified domain repository REMOVE (see page 1167) removes the certificate with a specified name GENERATE (see page 1173) generates a self-signed certificate

Remarks The SSL protection can be enabled on the domain hosted on a dedicated IP address.

1162

Supported Operations

In this section:
Installing Certificate ........................................................................................... 1162 Deleting Certificate ............................................................................................ 1167 Generating Certificate ....................................................................................... 1173

Installing Certificate
The install operation is used to install an SSL certificate to Administrator's certificate repository or to a specified domain repository. Please note that this operation only installs a certificate to a repository, it does not enable SSL support for a domain, therefore, it does not make the domain available via https protocol.

In this section:
Request Packet Structure.................................................................................. 1162 Request Samples .............................................................................................. 1164 Response Packet Structure ............................................................................... 1166 Response Samples ........................................................................................... 1167

Request Packet Structure


A request XML packet installing an SSL certificate to Plesk certificate repository includes the install operation node:
<packet version=1.4.2.0> <certificate> <install> </install> </certificate> </packet>

The install node does not have a separate data type, it is nested within type CertificateActionRequest (certificate_input.xsd). The install has the following graphical representation:

Supported Operations

1163

The name node is required.It specifies the name under which the certificate will be known in repository and in Plesk. Data type: string. The domain node is required. It specifies the domain repository to which the certificate is installed. Data type: string. The admin node is required. If the node is present in a request packet, the certificate is installed to the Administrator's repository. Data type: none. The content node is required. It contains all data constituting the certificate. Data type: none. The csr node is required. It specifies the certificate CSR (certificate signing request). Data type: string. The pvt node is required. It specifies the certificate private key. Data type: string. The cert node is optional. It contains the certificate body. Data type: string.

Remarks 1. Certificate name must be unique in Plesk, meaning that two certificates with the same name cannot be installed, even if you want to install them to different repositories. 2. You can install only one certificate to only one repository within one install operation. Therefore, you must include either one domain node or admin node. 3. With one packet, you can install as many different certificates to any of the repositories as you want. To install multiple certificates, use the required number of install nodes in the packet:
<packet version=1.4.2.0> <certificate> <install> </install> <install> </install> </certificate> </packet>

1164

Supported Operations

Request Samples
Installing certificate This packet installs to Administrator's repository certificate that will be known in Plesk under name general.
<packet version="1.4.2.0"> <certificate> <install> <name>general</name> <admin/> <content> <csr>-----BEGIN CERTIFICATE REQUEST----MIICwTCCAakCAQAwfDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB2dlb3JnaWExEDAO BgNVBAcTB0F0bGFudGExEjAQBgNVBAoTCURvZSwgTHRkLjEUMBIGA1UEAxMLam9o bmRvZS5vcmcxHzAdBgkqhkiG9w0BCQEWEGpkb2VAam9obmRvZS5vcmcwggEiMA0G CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC7AQlX0pXqCs61ZUZ28zJ9PAG0yxvV 2pJnJTMqrudyi/3vV8IZrBUUWMthf7tQmMSSyZWAqM+7n4Q9Y4f5WuR+3ReM5kxC hbQnOrjpdUmv1+ZhB9Q21UFA5eEptyDM/LR2JAjpKJD078rh76pVZm3EsJMl3+UE 3Dg0DeKDelDKa4SYzW1JJnoen4UXX37lIHdBnIj+NCQbHRSiGD6w6mMyiCMOzXCp SBiGXgRRcaOVl50OeAdVKkwpJaae1K7K3q9j/LkAlOa1C8kuwdaCtKC+jFCE72I0 Q8TnIn7ahPy0yd2EgzZ42Ys8D3PziqGax8I/e6BbEOfzi0n1HD9GCzaPAgMBAAGg ADANBgkqhkiG9w0BAQQFAAOCAQEAhoSVmInXLQDJu8jrZTVvFUx6O6aHOUkUf/G8 Wnc2x7w+Qo7XHMHVDCUcP3K+bEw9oKxfpvRXP9XTVhX2jABHrxywLyjg4cXwaUgR t7ULvpLQ0Sum5XNtBypAdSQZZ7ktAa6Q3OMAFNdY8YG9J/L2zlcL9JJZLAUnRWzN fMBn9Ip3pCC8N9OF9+PFpxGvhtlc1O27w9wj0RdK3hF6Rg37qcUJSnn6XxOB41Q8 ZZbX2Vbskz0WJ1IcxsfWDJ/HFdho7GrrD/wujNpwkTPc3xe2AHcfQX8c/92xyra/ kdzxsDdFD7IwA5bBWGm8QwlL9yWuDPiZ8vSGw96D/Qije9UVkA== -----END CERTIFICATE REQUEST-----</csr> <pvt>-----BEGIN RSA PRIVATE KEY----MIIEpQIBAAKCAQEAyxfczy4HqgwOI6yxEa+dLaMLe5zC0ijcawsha8oFtJlxv/DM 9INpdKjv9HaInrR0StjG9HgqTpYrhOCJxeB07/gGsQ82xsvbcKANuCSQKInpwVim GUsisGNrfnbKIoAewN21ENCZQrufcQNWNzTx/GjVCXqa/Sy4pXJ6Jud0dzA/+Vis SBw5Oo4IqI2MDvuoDk+exQLdgM45Vgq4d3A9+ESzmRmjmdovhNxnXdvMxA5RSrF+ GZlBTFftsLQsnfnNiMR6ZTFgNCt2vdDmUAV9iix2B1PuoH94TRCJRG5tVCFtfVzS Rjo4ZzoiUs57efb3Oe56Lb64Ubi9ZRzNhdkGLwIDAQABAoIBABJdOAQr31mK+YRU SzaUMJw9z/3/cMZcF4I+YWlDvTxVW6nFdmLttw1rcTcjuLrRCmryKxtT+k9c2NaN DygrYaeJP+GmxIc5S8BlWJg8BiUEQ3TONUa4OozEkKXAzApOl3lNEuBQXGtiV8p6 SMN5MCBowkq3IWifMJsVPOJjr25Pby04HCPeeM+cnEiPnMrBjK4OGH8/pKqedf05 EcjnFKGFP2G0BUEhLX7ooMhB+AbjoIbGFXlBIzhaofs8zzSjNkKJ9i4LQMEe0GDf zCgE4GehW+FdcUlhG1zO7FOJc0LdVUR4deoMzaiNRIwdWxbokVwgSEnM20yXYdCl t+dsREECgYEA+sNPkzdQC0vF6me6WO8EqMu6AbPjObKnw0i8+g8ndRkMcJQ8FEXD +D447fCMORUdqGFH8aMWDp392z4JX3+ksSN9XtyEEKB3fsknENsDZKVJvh9U+gUD DO12mC1PleQBHBjN7Wlsg4mPZNv3cxUQLhFU0qW/moQdy0JrDfv+51ECgYEAz1Ww OJolOjKhPkGxiDY9sh95E/rpuwkGjb0qiS/UFHHuLc9pDYHyKRpPggdT4nEuBz34 cRpihMgxBKEzuXGEPvdIST0aObOwcqfY4HAJ8PS08rZupCJsk413gYeI/ckXacQK bYYHLKSEavrcmMFc98i2fmbbNp+ckeLHfzVYtX8CgYEAyP6X39YsEIHRx4sQ8IvU 3j89fnPjo7GxinPZFU3kQJWtROdsKIurAmVNWFrA6lgkh3xCIEqqOVklyv+0n5k+ NsXNjaWPLYyRe0xcRcRmudtKelu+zxAJW+lSb7OR4QD6arzvAmbIFb7C8wLlGpc9 es9lf9pe88kF4JACIxljPaECgYEAj4sWtwlZbsJwygZ3YAOVkUWi8QdNXLVx+R2X XmVjokgCi2rGo5hszLIvi6mBFQwgvtjTsZJ/1Mg4z6i/g8sosONJA5OvHXXfWnIE f9Zxu4Xf5Q4S6cX/f+R4cZAhcvsPH6WfRpZ9TxYTq3FE2uk8cTxfxIF3kYjNwF7O ma6YXQcCgYEApqdVVr92YSYZuDTKYGN5Rd5BaJSGPYWpShS5lPKBQ4n/TkSZzO1v Bxq2AbPRohXasWEAdfgfss1mcwX9xnKO/DhnxXE8KVFXKVehGmUth0WqA5qtL4xD h4hm3V7DcMqYbVzpmlWXFz5Is1fIflAhlfeX4h3s1rirTj+T6hODVf4= -----END RSA PRIVATE KEY-----</pvt> <cert>-----BEGIN CERTIFICATE----MIIDiTCCAnECBETUDecwDQYJKoZIhvcNAQEEBQAwgYgxCzAJBgNVBAYTAlJVMQww

Supported Operations

1165

CgYDVQQIEwNOU08xDDAKBgNVBAcTA05TSzEUMBIGA1UEChMLRGFtYWdlIEluYy4x CzAJBgNVBAsTAlFBMRcwFQYDVQQDEw53d3cuc3dzb2Z0LmNvbTEhMB8GCSqGSIb3 DQEJARYScmJ1c3lndWluQHBsZXNrLnJ1MB4XDTA2MDgwNTAzMTgwMVoXDTA3MDgw NTAzMTgwMVowgYgxCzAJBgNVBAYTAlJVMQwwCgYDVQQIEwNOU08xDDAKBgNVBAcT A05TSzEUMBIGA1UEChMLRGFtYWdlIEluYy4xCzAJBgNVBAsTAlFBMRcwFQYDVQQD Ew53d3cuc3dzb2Z0LmNvbTEhMB8GCSqGSIb3DQEJARYScmJ1c3lndWluQHBsZXNr LnJ1MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyxfczy4HqgwOI6yx Ea+dLaMLe5zC0ijcawsha8oFtJlxv/DM9INpdKjv9HaInrR0StjG9HgqTpYrhOCJ xeB07/gGsQ82xsvbcKANuCSQKInpwVimGUsisGNrfnbKIoAewN21ENCZQrufcQNW NzTx/GjVCXqa/Sy4pXJ6Jud0dzA/+VisSBw5Oo4IqI2MDvuoDk+exQLdgM45Vgq4 d3A9+ESzmRmjmdovhNxnXdvMxA5RSrF+GZlBTFftsLQsnfnNiMR6ZTFgNCt2vdDm UAV9iix2B1PuoH94TRCJRG5tVCFtfVzSRjo4ZzoiUs57efb3Oe56Lb64Ubi9ZRzN hdkGLwIDAQABMA0GCSqGSIb3DQEBBAUAA4IBAQBH8mTX3Q3csBUjzwfy3kIVobgh yElljOQ87Qv5rht5yktuTyS3oGXsDD0sO/uSG/akL34CTPkjl/vqYtzKMsfQ5pXY MlY6Q+GCd9FgL5pBn1S8HSZLpTBWZc25mNe3mXbCQzI03r4W+dQajAgAgDKpnRjg mblRg98+HwOL033pVgUnRwPoS3LO5jia5z3F0MkS8sV3x18DuoSLeVILhj0ttZ/p B7x0kIUee8A95Q00EDh+4IaPSMOqiFrVIlsHEuPV33aCAz2Dk2TxzplsoNz61BFA i3Cm04Gz1h9W/yzkcYCqiwUMIzSgUSBLn0hBeTid1u/NaDtic776YGuyaI+/ -----END CERTIFICATE-----</cert> </content> </install> </certificate> </packet>

Installing several certificates This packet installs two certificates to repositories of domains doe.de and johndoe.org.
<packet version="1.4.2.0"> <certificate> <install> <name>common</name> <domain>doe.de</domain> <content> <csr>-----BEGIN CERTIFICATE REQUEST----MIIBujCCASMCAQAwejELMAkGA1UEBhMCQUYxDjAMBgNVBAgTBVN0YXRlMQ0wCwYD VQQHEwRDaXR5MRQwEgYDVQQKEwtEYW1hZ2UgSW5jLjETMBEGA1UEAxMKZG9tYWlu LmNvbTEhMB8GCSqGSIb3DQEJARYScmJ1c3lndWluQHBsZXNrLnJ1MIGfMA0GCSqG SIb3DQEBAQUAA4GNADCBiQKBgQC7s14ervVsRk64NHKgHppXJCy4gMX/sdHxxlov g8tloYB5/OEL2j5oK1PH9AyF/1d6sLJzve/2i+CE5/nvsKxWC8INT4HnTlsFbyIm m80JRp0jq3cLLv43uEvB8P94ihAjXL3KDTg6D+MSvRJyfuDM5xWTia2Wsh9rNM+h 8td3HwIDAQABoAAwDQYJKoZIhvcNAQEEBQADgYEArsjs3Q3SiktL0lWSRi/jTF5d Q7ZITADvUveeTDF2k9ai9u3gWnRVw0q2t+001niVBACzNIN3luyJDdC9V7Y1XeJ9 hmmgZf1vgJN7waDZ/7GBG+ZySEnqHOnQo2cGPbZ7HaF2GTn67F5fHu52/HhtlPrt 5OLH+Ftv5Z1cy3kziqE= -----END CERTIFICATE REQUEST-----</csr> <pvt>-----BEGIN RSA PRIVATE KEY----MIICXQIBAAKBgQC7s14ervVsRk64NHKgHppXJCy4gMX/sdHxxlovg8tloYB5/OEL 2j5oK1PH9AyF/1d6sLJzve/2i+CE5/nvsKxWC8INT4HnTlsFbyImm80JRp0jq3cL Lv43uEvB8P94ihAjXL3KDTg6D+MSvRJyfuDM5xWTia2Wsh9rNM+h8td3HwIDAQAB AoGAbRjYP+VZaNGEt7RkW4TuGHBCPgs7Cl+Es46ipLNp6WxxjHXbKFR1qX5ld/b1 wHylj/5b+sIPU7IBkb5zm0mJIItK3VpwYLZVn9sM8REOKVNjXPkxjoKH/w8TdS+8 o4tb/cmjQhClu2e1TBG0RvlK2KXNpohBHkFeHRsFNVhwzCECQQDiJwOQ9vGiWG40 fPyLOrv6REbrjAT4vmQ5SyXX1PWs8grlVd4/hevt6LmbG9sq0suV20BL32pj3XEN mo5O6jNLAkEA1HkwXYo2cKNpqLkHj7P4LbJZ2yjh5LLRYO5a3EPyWDb0N9lkqrlZ F00KIeFZfRCZhTrHp+KdFklMpbMm9SaS/QJBAImIkHKou2qvvNXO7Qb/QTKCM18s WBmuL+Vn/iu0J3R1/opaHj8jgse8sKPT3QW+DHGmVQPPazQwh4Bubf0wEOECQQCB Xsj0K5O6QcWz1fWkqhASwuWza9EfT0HtozPvqe+FhvBskRGaYgC9D0t8FZpHbDQN yxyGPJUpXLgurEasPjCBAkA3AWOwcg2yYY/dQws81lHZd6I4l43PZtEiJ0C/k8tR

1166

Supported Operations OmU2Co29ysy1fids1zwVXXuyYeaKVLqMipfl+O2TADyg -----END RSA PRIVATE KEY-----</pvt> </content> </install> <install> <name>personal</name> <domain>johndoe.org</domain> <content> <csr>-----BEGIN CERTIFICATE REQUEST----MIIBtDCCAR0CAQAwdDELMAkGA1UEBhMCUlUxDDAKBgNVBAgTA05TTzEMMAoGA1UE BxMDTlNLMQ8wDQYDVQQKEwZTV1NvZnQxEzARBgNVBAMTCkNvbW1vbk5hbWUxIzAh BgkqhkiG9w0BCQEWFHJidXN5Z3VpbkBzd3NvZnQuY29tMIGfMA0GCSqGSIb3DQEB AQUAA4GNADCBiQKBgQDSMFNv0uCVotZ5p06dcdj6omA+DbowFRMb4G5KMzskY9fU CIc0jdGIHtFp5sjquq2HgWQDorW/xHlrI7sea/b7ILBzQPIwIgvDSornXoWwrr4Y ahMlFrAEYtgD4Fn/oiGoEVZsU6dm4ZZ8lknWMj0RzoWNvqV3v5N+YbT3f29ODQID AQABoAAwDQYJKoZIhvcNAQEFBQADgYEAmHzBx1AO2eOvk2mU/c9JLLV4amRDp28A xXt0ktThLgvwr9y3+jZaYSxRShI9VYJLHPiSqj4uJhvbHg6f9Y77uYwdBXPbR6j4 BPYrHn47kOqsL05VLVMxhDjechzx0rML0g9l1zsZnPLibukKhR4NSWiNgVwACBt1 s3KuVqK0qSE= -----END CERTIFICATE REQUEST-----</csr> <pvt>-----BEGIN RSA PRIVATE KEY----MIICWwIBAAKBgQDSMFNv0uCVotZ5p06dcdj6omA+DbowFRMb4G5KMzskY9fUCIc0 jdGIHtFp5sjquq2HgWQDorW/xHlrI7sea/b7ILBzQPIwIgvDSornXoWwrr4YahMl FrAEYtgD4Fn/oiGoEVZsU6dm4ZZ8lknWMj0RzoWNvqV3v5N+YbT3f29ODQIDAQAB AoGALjjKYHDzSnTAzYfpVd5PZO6IU50ZMLGxvhOgrViOzPXX5JzrfrchONnuG2fR Dy12M7JUmCgT59QBD3qQD6SWb0T3awJFiJdGe7qZxSIc/dCYnVStrk8veYY1LQtV 78QaRxp71l+XdHiaMKkqL57YyK2Yv+EJy4XVqbX7wOJX6ghchFIbfScSowJAfaJi jXmo8bHXvoNWKyiwtA6tqxrQVh74+WSPcZDhVt2PgBVbrhhaaqw7kEZkgvFh1X5r QBtSQyb59VW6oJSa4QJAVz54Z+Jvga1x1xN9f0RTHipRorimmth2obBHAZ/uXqYQ mRygqkRBDP+KgjhECJjIkPuT0q7zHBam2TfcH4vAwA== -----END RSA PRIVATE KEY-----</pvt> </content> </install> </certificate> </packet>

Response Packet Structure


The install node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. The status node is required. Specifies the execution status of the install operation. Data type: string. Allowed values: ok | error.

Supported Operations

1167

The errcode node is optional. Is used to return the error code when the install operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the install operation fails. Data type: string.

Response Samples
Positive response from server looks as follows:
<packet version="1.4.2.0"> <certificate> <install> <result> <status>ok</status> </result> </install> </certificate> </packet>

Negative responses from server can look as follows:


<packet version="1.4.2.0"> <certificate> <install> <result> <status>error</status> <errcode>8002</errcode> <errtext>Unable to set csr content to certificate : CSR field contains an improper value : openssl failed: </errtext> </result> </install> </certificate> </packet>

<packet version="1.4.2.0"> <certificate> <install> <result> <status>error</status> <errcode>8006</errcode> <errtext>Unable to set certificate name : </errtext> </result> </install> </certificate> </packet>

Response packet with the error is received from the server if the name node in a request packet contains the name of certificate already installed to one of the repositories.

1168

Supported Operations

Deleting Certificate
Use the remove operation to remove one or more certificates within one repository, whether it is a particular domain repository or Administrator's repository.

In this section:
Request Packet Structure.................................................................................. 1168 Request Samples .............................................................................................. 1170 Response Packet Structure ............................................................................... 1171 Response Samples ........................................................................................... 1172

Request Packet Structure


A request XML packet that deletes certificate should include the remove operation node:
<packet version=1.4.2.0> <certificate> <remove> </remove> </certificate> </packet>

The remove node does not have a separate type, it is nested within type CertificateActionRequest (certificate_input.xsd). The remove node has the following graphical representation:

The filter node is required. It contains rules defining which certificates should be deleted. Data type: none. The name node is required. It specifies the name of certificate that should be deleted. Data type: string. The domain node is required. It specifies form which domain repository the certificate is deleted. Data type: string. The admin node is required. It specifies that the certificate is deleted from Administrator's repository . Data type: none.

Supported Operations

1169

Remarks 1. The filter node allows specifying multiple certificate names, which gives you opportunity to delete several certificates within one remove operation.
<packet version=1.4.2.0> <certificate> <remove> <filter> <name>cert_1</name> <name>cert_2</name> <name>cert_3</name> <name>cert_4</name> </filter> </remove> </certificate> </packet>

2. With a single remove operation, you can delete certificates from only one repository which is defined with required domain or admin node. In other words, you should use either domain node, or admin node within remove operation nodes:
<packet version=1.4.2.0> <certificate> <remove> <filter> </filter> <domain>domain1.com</domain> </remove> </certificate> </packet>

or
<packet version=1.4.2.0> <certificate> <remove> <filter> </filter> <admin/> </remove> </certificate> </packet>

3. With one packet, you can remove multiple different certificates from any of the repositories you own. To do this, use the required number of remove nodes in the packet:
<packet version=1.4.2.0> <certificate> <remove> </remove> <remove> </remove> </certificate> </packet>

1170

Supported Operations

Request Samples
Removing certificate This packet removes certificate called common from repository of domain doe.de.
<packet version="1.4.2.0"> <certificate> <remove> <filter> <name>common</name> </filter> <domain>doe.de</domain> </remove> </certificate> </packet>

This packet removes certificate called shared from Administrator's repository.


<packet version="1.4.2.0"> <certificate> <remove> <filter> <name>shared</name> </filter> <admin/> </remove> </certificate> </packet>

Removing several certificates This packet removes three certificates: general, personal, sample. Certificate general is installed to Administrator's repository. Certificates personal and sample are installed to the repository of domain johndoe.org.
<packet version="1.4.2.0"> <certificate> <remove> <filter> <name>general</name> </filter> <admin/> </remove> <remove> <filter> <name>personal</name> <name>sample</name> </filter> <domain>johndoe.org</domain> </remove> </certificate> </packet>

Supported Operations

1171

Response Packet Structure


The remove node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the remove operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It is used to return the error code when the remove operation fails. Data type: unsignedInt. The errtext node is optional. It is used to return the error message if the remove operation fails. Data type: string. The name node is optional. Returns the certificate name if the certificate is not found on the server. Data type: string.

1172

Supported Operations

Response Samples
Positive responses received from the server after successful removing of certificates look as follows:
<packet version="1.4.2.0"> <certificate> <remove> <result> <status>ok</status> </result> </remove> </certificate> </packet>

<packet version="1.4.2.0"> <certificate> <remove> <result> <status>ok</status> </result> </remove> <remove> <result> <status>ok</status> </result> <result> <status>ok</status> </result> </remove> </certificate> </packet>

A negative response received from the server can look as follows:


<packet version="1.4.2.0"> <certificate> <remove> <result> <status>error</status> <errcode>1013</errcode> <errtext>Certificate does not exist </errtext> <name>common</name> </result> </remove> </certificate> </packet>

Supported Operations

1173

Generating Certificate
The generate operation is used for generating self-signed SSL certificate, which then can be installed to a repository. For installation details, refer to the Installing Certificate (see page 1162) section.

In this section:
Request Packet Structure.................................................................................. 1173 Request Samples .............................................................................................. 1175 Response Packet Structure ............................................................................... 1176 Response Samples ........................................................................................... 1176

Request Packet Structure


A request XML packet that generates self-signed certificate should include the generate operation node:
<packet version=1.4.2.0> <certificate> <generate> </generate> </certificate> </packet>

The generate node does not have a separate data type, it is nested in type CertificateActionRequest (certificate_input.xsd). The node has the following graphical representation:

1174

Supported Operations

The info node is required. It contains the set of parameters required for generating certificate components. Data type: none. The bits node is required. It defines the size of certificate in bits. Data type: integer. Allowed values: 1024 | 2048. The country node is required. It specifies the country where your business operates. Data type: string. Value restrictions: two-letters upper-case country nomination in accordance with ISO 3166 (http://www.iso.org/iso/en/prodsservices/iso3166ma/02iso-3166-code-lists/list-en1.html). The state node is required. It specifies the state or province where your business operates. Data type: string. Value restrictions: full name of state/ province in lower case (e.g., "california"), or two-letters upper-case indication (e.g., "CA"). The location node is required. It specifies the name of the city where your business operates. Data type: string. The company node is required. It specifies the name of the company with which the certificate will be associated. Data type: string. The dept node is optional. It specifies the company department. Data type: string. The email node is required. It specifies your e-mail address that will be used for generating CSR component of the certificate. Data type: string. The name node is required. It specifies the name of the domain with which the certificate should be associated. Data type: string. The PVT node is optional. It defines the private key part of the certificate. Data type: string.

Remarks With one packet, you can generate multiple certificates. To do this, use the required number of generate nodes in the packet:
<packet version=1.4.2.0> <certificate> <generate> </generate> <generate> </generate> </certificate> </packet>

Supported Operations

1175

Request Samples
This packet generates 2048-bit certificate that associates domain johndoe.org with company Doe, Ltd. operating its business in United States, Georgia, Atlanta.
<packet version=1.4.2.0> <certificate> <generate> <info> <bits>2048</bits> <country>US</country> <state>georgia</state> <location>Atlanta</location> <company>Doe, Ltd.</company> <email>jdoe@johndoe.org</email> <name>johndoe.org</name> </info> </generate> </certificate> </packet>

This packet, using existing private key, generates 1024-bit certificate that associates domain johndoe.org with company Doe BV operating its business in Germany, Mnchen.
<packet version=1.4.2.0> <certificate> <generate> <info> <bits>1024</bits> <country>DE</country> <state>bavaria</state> <location>muenchen</location> <company>Doe BV</company> <email>jdoe@johndoe.org</email> <name>johndoe.org</name> </info> <pvt>-----BEGIN RSA PRIVATE KEY----MIIEpAIBAAKCAQEAuwEJV9KV6grOtWVGdvMyfTwBtMsb1dqSZyUzKq7ncov971fC GawVFFjLYX+7UJjEksmVgKjPu5+EPWOH+Vrkft0XjOZMQoW0Jzq46XVJr9fmYQfU NtVBQOXhKbcgzPy0diQI6SiQ9O/K4e+qVWZtxLCTJd/lBNw4NA3ig3pQymuEmM1t SSZ6Hp+FF19+5SB3QZyI/jQkGx0Uohg+sOpjMogjDs1wqUgYhl4EUXGjlZedDngH VSpMKSWmntSuyt6vY/y5AJTmtQvJLsHWgrSgvoxQhO9iNEPE5yJ+2oT8tMndhIM2 oiZGL2kCgYBRi0j2Fe3ZxX6PWYogmS17pZdta6Dyuh90w4dfYyEM8RtHo67L6i4j pYpvyiF7C4Rklh3+MJfk1VkqQGNmPAT2H1eK4fQ6LH14t8oiFJbCok/SnKC2BUMt UJLKqgqP591cN0xpbdH/9k1nGdNxi9z1myA7gSrKNIzSnQFSqn4lAg== -----END RSA PRIVATE KEY----</pvt> </generate> </certificate> </packet>

1176

Supported Operations

This request packet is incorrect because country node contains a full country name, not a country nomination in accordance with ISO 3166.
<packet version="1.4.2.0"> <certificate> <generate> <info> <bits>512</bits> <country>Germany</country> <state>bavaria</state> <location>muenchen</location> <company>Doe BV</company> <email>jdoe@johndoe.org</email> <name>johndoe.org</name> </info> </generate> </certificate> </packet>

Response Packet Structure


The generate node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data Type: resultType (common.xsd). The status node is required. Specifies the execution status of the generate operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is used to return the error code when the generate operation fails. Data type: unsignedInt. The errtext node is optional. Can be used to return the error message if the generate operation fails. Data type: string. The csr node is required. It contains the CSR component of generated certificate. Data Type: string. The pvt node is optional. It contains the Private Key component of generated certificate. Data Type: string.

Supported Operations

1177

Response Samples
A positive response received from server after generating certificate can look as follows:
<packet version="1.4.2.0"> <certificate> <generate> <result> <status>ok</status> <csr>-----BEGIN CERTIFICATE REQUEST----MIICwTCCAakCAQAwfDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB2dlb3JnaWExEDAO BgNVBAcTB0F0bGFudGExEjAQBgNVBAoTCURvZSwgTHRkLjEUMBIGA1UEAxMLam9o bmRvZS5vcmcxHzAdBgkqhkiG9w0BCQEWEGpkb2VAam9obmRvZS5vcmcwggEiMA0G CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC7AQlX0pXqCs61ZUZ28zJ9PAG0yxvV 2pJnJTMqrudyi/3vV8IZrBUUWMthf7tQmMSSyZWAqM+7n4Q9Y4f5WuR+3ReM5kxC hbQnOrjpdUmv1+ZhB9Q21UFA5eEptyDM/LR2JAjpKJD078rh76pVZm3EsJMl3+UE 3Dg0DeKDelDKa4SYzW1JJnoen4UXX37lIHdBnIj+NCQbHRSiGD6w6mMyiCMOzXCp SBiGXgRRcaOVl50OeAdVKkwpJaae1K7K3q9j/LkAlOa1C8kuwdaCtKC+jFCE72I0 Q8TnIn7ahPy0yd2EgzZ42Ys8D3PziqGax8I/e6BbEOfzi0n1HD9GCzaPAgMBAAGg ADANBgkqhkiG9w0BAQQFAAOCAQEAhoSVmInXLQDJu8jrZTVvFUx6O6aHOUkUf/G8 Wnc2x7w+Qo7XHMHVDCUcP3K+bEw9oKxfpvRXP9XTVhX2jABHrxywLyjg4cXwaUgR t7ULvpLQ0Sum5XNtBypAdSQZZ7ktAa6Q3OMAFNdY8YG9J/L2zlcL9JJZLAUnRWzN fMBn9Ip3pCC8N9OF9+PFpxGvhtlc1O27w9wj0RdK3hF6Rg37qcUJSnn6XxOB41Q8 ZZbX2Vbskz0WJ1IcxsfWDJ/HFdho7GrrD/wujNpwkTPc3xe2AHcfQX8c/92xyra/ kdzxsDdFD7IwA5bBWGm8QwlL9yWuDPiZ8vSGw96D/Qije9UVkA== -----END CERTIFICATE REQUEST-----</csr> <pvt>-----BEGIN RSA PRIVATE KEY----MIIEpAIBAAKCAQEAuwEJV9KV6grOtWVGdvMyfTwBtMsb1dqSZyUzKq7ncov971fC GawVFFjLYX+7UJjEksmVgKjPu5+EPWOH+Vrkft0XjOZMQoW0Jzq46XVJr9fmYQfU Nx2uhi+plWc01PTI217uh80CgYEAomuM/RjDAdavjV2DZvPzuOw97WEeNHdzqYOq 0+eBrlR4uEAbr6+DOhfQuCr1bGM4RvGFwiGS6i9ROcPkXegUfoljrsrkeSluDkvQ 2322JXBZukFfTN4uaMNaYuoPAhI5Gmyw0b0/z51KE5u9fqKo7Sdhz6RWZR/+YGXE oiZGL2kCgYBRi0j2Fe3ZxX6PWYogmS17pZdta6Dyuh90w4dfYyEM8RtHo67L6i4j pYpvyiF7C4Rklh3+MJfk1VkqQGNmPAT2H1eK4fQ6LH14t8oiFJbCok/SnKC2BUMt UJLKqgqP591cN0xpbdH/9k1nGdNxi9z1myA7gSrKNIzSnQFSqn4lAg== -----END RSA PRIVATE KEY-----</pvt> </result> </generate> </certificate> </packet>

A negative response received from server can look as follows:


<packet version="1.4.2.0"> <certificate> <generate> <result> <status>error</status> <errcode>1019</errcode> <errtext>The parameter 'country' has improper value</errtext> </result> </generate> </certificate> </packet>

This packet is received in response to request packet that contained line <country>Germany</country>.

1178

Supported Operations

Managing SSO Service


Operator: <sso> XML Schema: sso.xsd Plesk version: 8.3 API RPC version: 1.5.2.0 Plesk user: Plesk Administrator Description Single Sign-on (SSO) is a specialized form of authentication that allows a user to enter login and password only once during session of interaction with several Web applications. Use the sso operator to configure SSO service in Plesk. Before configuring SSO branding, read the Configuring SSO Branding (on page 1191) section. The operator is also used for managing delegation rules. The rules define what users of a specific application (registered in the same IdP as Plesk) can be authorized in Plesk. For details on SSO, refer to the OPEN FUSION SSO Developer's Guide. Supported operations

Supported Operations

1179

ENABLE (on page 1181) enables SSO support in Plesk DISABLE (on page 1183) disables SSO support in Plesk REGISTER (on page 1186) registers Plesk in an IdP GET-PREFS (on page 1188) retrieves SSO service preferences SSO branding operations: SET-DEFAULT-IDP (on page 1191) changes Plesk default IdP URL GET-DEFAULT-IDP (on page 1195) retrieves Plesk default IdP URL RESTORE-DEFAULT-IDP (on page 1197) restores Plesk default IdP URL SET-BRANDED-IDP (on page 1199) sets a branded IdP URL for a specific domain GET-BRANDED-IDP (on page 1202) retrieves a branded IdP URL for a specific domain DEL-BRANDED-IDP (on page 1207) removes a branded IdP Operations on delegation rules: ADD-DELEGATION-RULE (on page 1212) adds a delegation rule DEL-DELEGATION-RULE (on page 1215) removes a delegation rule

In this section:
Filtering Issues .................................................................................................. 1179 Enabling SSO Service ....................................................................................... 1181 Disabling SSO Service ...................................................................................... 1183 Registering Plesk in IdP .................................................................................... 1186 Retrieving SSO Service Preferences ................................................................. 1188 Configuring SSO Branding ................................................................................ 1191 Adding Delegation Rule ..................................................................................... 1212 Removing Delegation Rule ................................................................................ 1215

Filtering Issues
Filtering is the way the request XML packet indicates the object to which an operation will be applied. The request XML packet filters objects using a special <filter> section. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

1180

Supported Operations

SSOGetRelayFilter Filter
The SSOGetRelayFilter filter is used in the get-branded-idp operation. For more information on the operation, refer to the Retrieving Branded IdP URL (on page 1202) section. Data type:SSOGetRelayFilter (sso.xsd). The graphical representation of the filter node is as follows:

The http-request-domain node is required. It specifies the name of the domain for which the branded IdP URL is retrieved. Data type: string.

Remarks You can match multiple domains as in the following example:


<filter> <http-request-domain>example.com</http-request-domain> <http-request-domain>example2.com</http-request-domain> </filter>

You can match all domains available for a packet sender as in the following example:
<filter/>

SSODelRelayFilter Filter
The SSODelRelayFilter filter is used in del-branded-idp operation. For more information on the operation, refer to the Removing Branded IdP URL (on page 1207) section. Data type:SSODelRelayFilter (protected_dir.xsd). The graphical representation of the filter node is as follows:

The idp-url node is required. It specifies the branded IdP URL. Data type: base64. The http-request-domain node is required. It specifies the name of the domain for which the branded IdP URL is set. Data type: string.

Supported Operations

1181

Remarks You can match URLs of multiple branded IdPs by names of domains which use them as in the following example:
<filter> <http-request-domain>example.com</http-request-domain> <http-request-domain>example2.com</http-request-domain> </filter>

You can match multiple branded IdPs by their URLs as in the following example:
<filter> <relay-url>sso.example.com:1180/relay</relay-url> <relay-url>sso.example2.com:1180/relay</relay-url> </filter>

Note: Use the blank filter (<filter/>) to match all branded IdPs available for a packet sender.

filter-id Node

If an operation uses filters in a request packet, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filtering rule, it is returned in the filter-id node of the response packet. Domain name IdP URL

It is done to trace the request parameters in case of an error. Data type: anySimple. Note: If the request packet uses blank filter (<filter/>), the filter-id node value will contain the URL of the IdP affected by an operation. All operations except for the del-branded-idp and get-branded-idp do not possess the filterid node in the response packet.

Enabling SSO Service


Use the enable operation to enable SSO support in Plesk. You can enable the service only if it is registered in an IdP.

In this section:
Request Packet ................................................................................................. 1182 Response Packet Structure ............................................................................... 1182 Response Samples ........................................................................................... 1183

1182

Supported Operations

Request Packet
A request XML packet enabling SSO support includes the enable operation node:
<packet version="1.5.2.0"> <sso> <enable/> </sso> </packet>

The enable node is required. Data type: none.

Response Packet Structure


The enable node of the output XML packet is presented by type SSOEnableOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the enable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the enable operation fails. Data type: integer. The errtext node is optional. It returns the error message if the enable operation fails. Data type: string.

Supported Operations

1183

Response Samples
This request packet enables the SSO support on the server.
<packet version="1.5.2.0"> <sso> <enable/> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <enable> <result> <status>ok</status> </result> </enable> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <enable> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </enable> </sso> </packet>

1184

Supported Operations

Disabling SSO Service


Use the disable operation to disable SSO support in Plesk. You can disable the service only if it is currently started.

In this section:
Request Packet ................................................................................................. 1184 Response Packet Structure ............................................................................... 1184 Response Samples ........................................................................................... 1185

Request Packet
A request XML packet disabling SSO support includes the disable operation node:
<packet version="1.5.2.0"> <sso> <disable/> </sso> </packet>

The disable node is required. Data type: none.

Response Packet Structure


The disable node of the output XML packet is presented by type SSODisableOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the disable operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the disable operation fails. Data type: integer.

Supported Operations

1185

The errtext node is optional. It returns the error message if the disable operation fails. Data type: string.

Response Samples
This request packet disables the SSO support on the server.
<packet version="1.5.2.0"> <sso> <disable/> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <disable> <result> <status>ok</status> </result> </disable> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <disable> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </disable> </sso> </packet>

1186

Supported Operations

Registering Plesk in IdP


Use the register operation to register Plesk in a specific IdP. Note: To change the IdP URL, use the set-branded-idp operation. For details, refer to ...

In this section:
Request Packet Structure.................................................................................. 1186 Request Samples .............................................................................................. 1186 Response Packet Structure ............................................................................... 1187 Response Samples ........................................................................................... 1188

Request Packet Structure


A request XML packet registering Plesk in a specific IdP includes the register operation node:
<packet version="1.5.2.0"> <sso> <register> ... </register> </sso> </packet>

The register node is presented by type SSORegisterInput (sso.xsd), and its graphical representation is as follows:

The idp-url node is required. It specifies URL of the IdP. Data type: base64.

Request Samples
This request packet registering Plesk in the IdP service located at http://example.com:11443/.
<packet version="1.5.2.0"> <sso> <register> <idp-url>aHR0cDovL2V4YW1wbGUuY29tOjExNDQzLw==</idp-url> </register> </sso> </packet>

Supported Operations

1187

Response Packet Structure


The register node of the output XML packet is presented by type SSORegisterOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

1188

Supported Operations

Response Samples
This request packet registering Plesk in the IdP service located at http://example.com:11443/.
<packet version="1.5.2.0"> <sso> <register> <idp-url>aHR0cDovL2V4YW1wbGUuY29tOjExNDQzLw==</idp-url> </register> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <register> <result> <status>ok</status> </result> </register> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.1.0"> <sso> <register> <result> <status>error</status> <errcode>1035</errcode> <errtext>The service is busy.</errtext> </result> </register> </sso> </packet>

Supported Operations

1189

Retrieving SSO Service Preferences


Use the get-prefs operation to retrieve preferences of the SSO service.

In this section:
Request Packet ................................................................................................. 1189 Response Packet Structure ............................................................................... 1189 Response Samples ........................................................................................... 1190

Request Packet
A request XML packet retrieving SSO service preferences includes the get-prefs operation node:
<packet version="1.5.2.0"> <sso> <get-prefs/> </sso> </packet>

The get-prefs node is required. Data type: none.

Response Packet Structure


The get-prefs node of the output XML packet is presented by type SSOGetPrefsOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

1190

Supported Operations

The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The prefs node is required. Data type: SSOPrefs (sso.xsd). It specifies SSO service preferences and has the following graphical presentation:

If it is present, the following nodes are required: The idp-url node specifies URL of an IdP if Plesk is registered in the IdP. Data type: base64. The enabled node defines if SSO service is enabled. Data type: boolean. The application-id node stores Plesk application ID (created by the IdP) if Plesk is registered in the IdP. Data type: string.

Response Samples
This request packet retrieves SSO service preferences.
<packet version="1.5.1.0"> <sso> <get-prefs/> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.1.0"> <sso> <get-prefs> <result> <status>ok</status> <prefs> <idp-url>aHR0cHM6Ly9zc28uZXhhbXBsZS5jb206MTExNDMv</idpurl> <enabled>true</enabled> <application-id>ac688844-2d14-46a1-8b6a93cfa</application-id> </prefs> </result> </get-prefs> </sso> </packet>

Supported Operations

1191

If the SSO service is disabled, the response from the server can look as follows:
<packet version="1.5.1.0"> <sso> <get-prefs> <result> <status>ok</status> <prefs> <enabled>false</enabled> </prefs> </result> </get-prefs> </sso> </packet>

Configuring SSO Branding


This section describes how to configure SSO Branding. For information on what SSO Branding is, refer to the ... section of the SSO Developer's Guide.

In this section:
Changing Default IdP URL ................................................................................ 1191 Retrieving Default IdP URL ............................................................................... 1195 Restoring Default IdP URL ................................................................................ 1197 Setting Branded IdP URL .................................................................................. 1199 Retrieving Branded IdP URL ............................................................................. 1202 Removing Branded IdP ..................................................................................... 1207

Changing Default IdP URL


The set-default-idp operation is used to change the default IdP URL (given to Plesk after its registration in IdP). For instance, the operation is used when the IdP domain name is changed. Note: The operation does not force Plesk to re-register in the IdP specified by a new default IdP URL.

In this section:
Request Packet Structure.................................................................................. 1192 Request Samples .............................................................................................. 1192 Response Packet Structure ............................................................................... 1193 Response Samples ........................................................................................... 1194

1192

Supported Operations

Request Packet Structure


A request XML packet changing the default IdP URL includes the set-default-idp operation node:
<packet version="1.5.2.0"> <sso> <set-default-idp> ... </set-default-idp> </sso> </packet>

The set-default-idp node is presented by type SSOSetDefaultRelayInput (sso.xsd), and its graphical representation is as follows:

The idp-url node is required. It specifies URL of the default IdP. Data type: base64.

Request Samples
The packet that changes the default IdP URL to http://sso.example.com:1180/ can look as follows:
<packet version="1.5.2.0"> <sso> <set-default-idp> <idp-url>aHR0cDovL3Nzby5leGFtcGxlLmNvbToxMTgwLw==</idpurl> </set-default-idp> </sso> </packet>

Supported Operations

1193

Response Packet Structure

The set-default-idp node of the output XML packet is presented by type SSOSetDefaultRelayOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

1194

Supported Operations

Response Samples
The packet that changes the default IdP URL to http://sso.example.com:1180/ can look as follows:
<packet version="1.5.2.0"> <sso> <set-default-idp> <idp-url>aHR0cDovL3Nzby5leGFtcGxlLmNvbToxMTgwLw==</idpurl> </set-default-idp> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <set-default-idp> <result> <status>ok</status> </result> </set-default-idp> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <set-default-idp> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </set-default-idp> </sso> </packet>

Supported Operations

1195

Retrieving Default IdP URL


Use the get-default-idp operation to retrieve the default IdP URL.

In this section:
Request Packet ................................................................................................. 1195 Response Packet Structure ............................................................................... 1195 Response Samples ........................................................................................... 1196

Request Packet
A request XML packet retrieving the default IdP URL includes the get-default-idp operation node:
<packet version="1.5.2.0"> <sso> <get-default-idp/> </sso> </packet>

The get-default-idp node is required. Data type: none.

Response Packet Structure


The get-default-idp node of the output XML packet is presented by type SSOGetDefaultRelayOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd).

1196

Supported Operations

The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The idp-url node is optional. It returns the default IdP URL if the operation succeeds. Data type: base64.

Response Samples
The packet that retrieves the default IdP URL can look as follows:
<packet version="1.5.2.0"> <sso> <get-default-idp/> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <get-default-idp> <result> <status>ok</status> <idp-url>aHR0cDovL3Nzby5leGFtcGxlLmNvbToxMTgwLw==</idp-url> </result> </get-default-idp> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <get-default-idp> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </get-default-idp> </sso> </packet>

Supported Operations

1197

Restoring Default IdP URL


Use the restore-default-idp operation to replace the default IdP URL with the IdP URL given to Plesk after its registration in IdP.

In this section:
Request Packet ................................................................................................. 1197 Response Packet Structure ............................................................................... 1197 Response Samples ........................................................................................... 1198

Request Packet
A request XML packet restoring the default IdP URL includes the restore-default-idp operation node:
<packet version="1.5.2.0"> <sso> <restore-default-idp/> </sso> </packet>

The restore-default-idp node is required. Data type: none.

Response Packet Structure


The restore-default-idp node of the output XML packet is presented by type SSORestoreDefaultRelayOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

1198

Supported Operations

The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Response Samples
The packet that restores the default IdP URL can look as follows:
<packet version="1.5.2.0"> <sso> <restore-default-idp/> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <restore-default-idp> <result> <status>ok</status> </result> </restore-default-idp> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <restore-default-idp> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </restore-default-idp> </sso> </packet>

Supported Operations

1199

Setting Branded IdP URL


Use the set-branded-idp operation to set the branded IdP for a specific domain.

In this section:
Request Packet Structure.................................................................................. 1199 Request Samples .............................................................................................. 1199 Response Packet Structure ............................................................................... 1200 Response Samples ........................................................................................... 1201

Request Packet Structure


A request XML packet setting the branded IdP URL for a domain includes the setbranded-idp operation node:
<packet version="1.5.2.0"> <sso> <set-branded-idp> ... </set-branded-idp> </sso> </packet>

The set-branded-idp node is presented by type SSOSetRelayInput (sso.xsd), and its graphical representation is as follows:

The idp-url node is required. It specifies the branded IdP URL. Data type: base64. The http-request-domain node is required. It specifies the name of the domain for which the branded IdP is set. Data type: string.

Note: The domain must not exist in Plesk. Remarks The operation will associate a domain with a new branded IdP even if it was previously associated with another IdP.

1200

Supported Operations

Request Samples
The packet that sets the branded IdP URL (http://sso.example.com:1180/) for domain example.com looks as follows:
<packet version="1.5.2.0"> <sso> <set-branded-idp> <idp-url>aHR0cDovL3Nzby5leGFtcGxlLmNvbToxMTgwLw==</idpurl> <http-request-domain>https://example.com:8443</httprequest-domain> </set-branded-idp> </sso> </packet>

Response Packet Structure


The set-branded-idp node of the output XML packet is presented by type SSOSetRelayOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Supported Operations

1201

Response Samples
The packet that sets the branded IdP URL (http://sso.example.com:1180/) for domain example.com looks as follows:
<packet version="1.5.2.0"> <sso> <set-branded-idp> <idp-url>aHR0cDovL3Nzby5leGFtcGxlLmNvbToxMTgwLw==</idpurl> <http-request-domain>https://example.com:8443</httprequest-domain> </set-branded-idp> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <set-branded-idp> <result> <status>ok</status> </result> </set-branded-idp> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <set-branded-idp> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </set-branded-idp> </sso> </packet>

If the domain does not exist in Plesk database, the response from the server looks as follows:
<packet version="1.5.2.0"> <sso> <set-branded-idp> <result> <status>error</status> <errcode>1013</errcode> <errtext>HTTP Request domain does not exist.</errtext> </result> </set-branded-idp> </sso> </packet>

1202

Supported Operations

Retrieving Branded IdP URL


Use the get-branded-idp operation to retrieve the branded IdP URL for a specific domain.

In this section:
Request Packet Structure.................................................................................. 1202 Request Samples .............................................................................................. 1203 Response Packet Structure ............................................................................... 1204 Response Samples ........................................................................................... 1205

Request Packet Structure


A request XML packet retrieving the branded IdP URL for a specific domain includes the get-branded-idp operation node:
<packet version="1.5.2.0"> <sso> <get-branded-idp> ... </get-branded-idp> </sso> </packet>

The get-branded-idp node is presented by type SSOGetRelayInput (sso.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 1180) section. Data type: SSOGetRelayFilter (sso.xsd).

Supported Operations

1203

Request Samples
Retrieving a single branded IdP URL The packet that retrieves the branded IdP URL for domain example.com looks as follows:
<packet version="1.5.2.0"> <sso> <get-branded-idp> <filter> <http-request-domain>example.com</http-request-domain> </filter> </get-branded-idp> </sso> </packet>

Retrieving multiple branded IdP URLs The packet that retrieves the branded IdP URLs for domains example.com and example2.com looks as follows:
<packet version="1.5.2.0"> <sso> <get-branded-idp> <filter> <http-request-domain>example.com</http-request-domain> <http-request-domain>example2.com</http-request-domain> </filter> </get-branded-idp> </sso> </packet>

The following packet retrieves branded IdPs URLs for all domains available for a packet sender.
<packet version="1.5.2.0"> <sso> <get-branded-idp> <filter/> </get-branded-idp> </sso> </packet>

1204

Supported Operations

Response Packet Structure


The get-branded-idp node of the output XML packet is presented by type SSOGetRelayOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 1181) section. Data type: anySimple. The id node is optional. It returns the branded IdP ID if the operation succeeds. Data type: integer. The record node is optional. It returns the branded IdP settings. Data type: SSOBrangingRecord (sso.xsd). The graphical presentation of this node is as follows:

Supported Operations

1205

The idp-url node is required. It specifies the URL of the branded IdP. Data type: base64. The http-request-domain node is required. It specifies the name of the domain for which the branded IdP is set. Data type: string.

Response Samples
Retrieving a single branded IdP URL The packet that retrieves the branded IdP URL for domain example.com looks as follows:
<packet version="1.5.2.0"> <sso> <get-branded-idp> <filter> <http-request-domain>example.com</http-request-domain> </filter> </get-branded-idp> </sso> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <get-branded-idp> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>42</id> <record> <idp-url>aWRwLmV4YW1wbGUyLmNvbToxMTgw</idp-url> <http-request-domain>example.com</http-requestdomain> </record> </result> </get-branded-idp> </sso> </packet>

1206

Supported Operations

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <get-branded-idp> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </get-branded-idp> </sso> </packet>

Retrieving multiple branded IdP URLs The packet that retrieves the branded IdP URLs for domains example.com and example2.com looks as follows:
<packet version="1.5.2.0"> <sso> <get-branded-idp> <filter> <http-request-domain>example.com</http-request-domain> <http-request-domain>example2.com</http-request-domain> </filter> </get-branded-idp> </sso> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <get-branded-idp> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>42</id> <record> <idp-url>aWRwLmV4YW1wbGUyLmNvbToxMTgw</idp-url> <http-request-domain>example.com</http-requestdomain> </record> </result> <result> <status>ok</status> <filter-id>example2.com</filter-id> <id>43</id> <record> <idp-url>c3NvLmV4YW1wbGUyLmNvbQ==</idp-url> <http-request-domain>example2.com</http-requestdomain> </record> </result> </get-branded-idp> </sso></packet>

Supported Operations

1207

Removing Branded IdP


Use the del-branded-idp operation to remove a branded IdP for a specific domain.

In this section:
Request Packet Structure.................................................................................. 1207 Request Samples .............................................................................................. 1208 Response Packet Structure ............................................................................... 1209 Response Samples ........................................................................................... 1210

Request Packet Structure


A request XML packet removing a branded IdP URL includes the del-branded-idp operation node:
<packet version="1.5.2.0"> <sso> <del-branded-idp> ... </del-branded-idp> </sso> </packet>

The del-branded-idp node is presented by type SSODelRelayInput (sso.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For details, refer to the Filtering Issues (on page 1180) section. Data type: SSODelRelayFilter (sso.xsd).

1208

Supported Operations

Request Samples
Removing a single branded IdP The packet that removes branded IdP linked to domain example.com looks as follows:
<packet version="1.5.2.0"> <sso> <del-branded-idp> <filter> <http-request-domain>example.com</http-request-domain> </filter> </del-branded-idp> </sso> </packet>

The packet that removes branded IdP idp.example.com:1180 looks as follows:


<packet version="1.5.2.0"> <sso> <del-branded-idp> <filter> <idp-url>aWRwLmV4YW1wbGUuY29tOjExODA=</idp-url> </filter> </del-branded-idp> </sso> </packet>

Removing multiple branded IdPs The packet that removes branded IdPs idp.example.com:1180 and idp.example2.com:1180 looks as follows:
<packet version="1.5.2.0"> <sso> <del-branded-idp> <filter> <idp-url>aWRwLmV4YW1wbGUuY29tOjExODA=</idp-url> <idp-url>aWRwLmV4YW1wbGUyLmNvbToxMTgw</idp-url> </filter> </del-branded-idp> </sso> </packet>

The packet that removes all branded IdPs available for a packet sender looks as follows:
<packet version="1.5.2.0"> <sso> <del-branded-idp> <filter/> </del-branded-idp> </sso> </packet>

Supported Operations

1209

Response Packet Structure


The del-branded-idp node of the output XML packet is presented by type SSODelRelayOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The filter-id node is optional. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 1181) section. Data type: anySimple. The id node is optional. It returns the ID of the removed branded IdP if the operation succeeds. Data type: integer.

1210

Supported Operations

Response Samples
Removing a single branded IdP The packet that removes branded IdP idp.example.com:1180 looks as follows:
<packet version="1.5.2.0"> <sso> <del-branded-idp> <filter> <idp-url>aWRwLmV4YW1wbGUuY29tOjExODA=</idp-url> </filter> </del-branded-idp> </sso> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <del-branded-idp> <result> <status>ok</status> <filter-id>aWRwLmV4YW1wbGUuY29tOjExODA=</filter-id> <id>42</id> </result> </del-branded-idp> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <del-branded-idp> <result> <status>error</status> <errcode>1026</errcode> <errtext>The service is not installed.</errtext> </result> </del-branded-idp> </sso> </packet>

Supported Operations

1211

If the branded IdP was not found in Plesk database, the response from the server looks as follows:
<packet version="1.5.2.0"> <sso> <del-branded-idp> <result> <result> <status>error</status> <errcode>1013</errcode> <errtext>Record does not exist.</errtext> </result> </result> </del-branded-idp> </sso> </packet>

Removing multiple branded IdPs The packet that removes branded IdPs idp.example.com:1180 and idp.example2.com:1180 looks as follows:
<packet version="1.5.2.0"> <sso> <del-branded-idp> <filter> <idp-url>aWRwLmV4YW1wbGUuY29tOjExODA=</idp-url> <idp-url>aWRwLmV4YW1wbGUyLmNvbToxMTgw</idp-url> </filter> </del-branded-idp> </sso> </packet>

A positive response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <del-branded-idp> <result> <status>ok</status> <filter-id>aWRwLmV4YW1wbGUuY29tOjExODA=</filter-id> <id>42</id> </result> <result> <status>ok</status> <filter-id>aWRwLmV4YW1wbGUyLmNvbToxMTgw</filter-id> <id>32</id> </result> </del-branded-idp> </sso> </packet>

1212

Supported Operations

Adding Delegation Rule


Use the add-delegation-rule operation to add a delegation rule.

In this section:
Request Packet Structure.................................................................................. 1212 Request Samples .............................................................................................. 1213 Response Packet Structure ............................................................................... 1213 Response Samples ........................................................................................... 1214

Request Packet Structure


A request XML packet adding a delegation rule includes the add-delegation-rule operation node:
<packet version="1.5.2.0"> <sso> <add-delegation-rule> ... </add-delegation-rule> </sso> </packet>

The add-delegation-rule node is presented by type SSOAddDelegationRuleInput (sso.xsd), and its graphical representation is as follows:

The sp-id node is required. It specifies ID of a specific service provider. A user of the SP (specified by sp-login) will be treated by Plesk as Plesk user specified by plesk-login. Data type: string. The sp-login node is required. It specifies the login of the SP user. Data type: string. The plesk-login node is required. It specifies the login of the Plesk user. Data type: string.

Supported Operations

1213

Request Samples
The packet that delegates resources of Plesk user MyUser to user MyExample registered at the SP specified by ID fvsrf4564asdsRdh4 looks as follows:
<packet version="1.5.2.0"> <sso> <add-delegation-rule> <sp-id>fvsrf4564asdsRdh4</sp-id> <sp-login>MyUser</sp-login> <plesk-login>MyExample</plesk-login> </add-delegation-rule> </sso> </packet>

Response Packet Structure


The add-delegation-rule node of the output XML packet is presented by type SSOAddDelegationRuleOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

1214

Supported Operations

Response Samples
The packet that delegates resources of Plesk user MyUser to user MyExample registered at the SP specified by ID fvsrf4564asdsRdh4 looks as follows:
<packet version="1.5.2.0"> <sso> <add-delegation-rule> <sp-id>fvsrf4564asdsRdh4</sp-id> <sp-login>MyUser</sp-login> <plesk-login>MyExample</plesk-login> </add-delegation-rule> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <add-delegation-rule> <result> <status>ok</status> </result> </add-delegation-rule> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <add-delegation-rule> <result> <status>error</status> <errcode>1035</errcode> <errtext>The SSO service is disabled.</errtext> </result> </add-delegation-rule> </sso> </packet>

Supported Operations

1215

Removing Delegation Rule


Use the del-delegation-rule operation to remove a delegation rule.

In this section:
Request Packet Structure.................................................................................. 1215 Request Samples .............................................................................................. 1216 Response Packet Structure ............................................................................... 1216 Response Samples ........................................................................................... 1217

Request Packet Structure


A request XML packet removing a delegation rule includes the del-delegation-rule operation node:
<packet version="1.5.2.0"> <sso> <del-delegation-rule> ... </del-delegation-rule> </sso> </packet>

The del-delegation-rule node is presented by type SSODelDelegationRuleInput (sso.xsd), and its graphical representation is as follows:

The sp-id node is required. It specifies ID of a specific service provider. A user of the SP (specified by sp-login) will be deprived of Plesk user's (specified by plesklogin) access to Plesk resources. Data type: string. The sp-login node is required. It specifies the login of the SP user. Data type: string. The plesk-login node is required. It specifies the login of the Plesk user. Data type: string.

1216

Supported Operations

Request Samples
The packet that deprives user MyExample (registered at the SP specified by ID fvsrf4564asdsRdh4) of access to Plesk user's MyUser resources looks as follows:
<packet version="1.5.2.0"> <sso> <del-delegation-rule> <sp-id>fvsrf4564asdsRdh4</sp-id> <sp-login>MyUser</sp-login> <plesk-login>MyExample</plesk-login> </del-delegation-rule> </sso> </packet>

Response Packet Structure


The del-delegation-rule node of the output XML packet is presented by type SSODelDelegationRuleOutput (sso.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error.

Note: If no delegation rules were found for a specific Plesk user, the operation status is ok. The errcode node is optional. It returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string.

Supported Operations

1217

Response Samples
The packet that deprives user MyExample (registered at the SP specified by ID fvsrf4564asdsRdh4) of access to Plesk user's MyUser resources looks as follows:
<packet version="1.5.2.0"> <sso> <del-delegation-rule> <sp-id>fvsrf4564asdsRdh4</sp-id> <sp-login>MyUser</sp-login> <plesk-login>MyExample</plesk-login> </del-delegation-rule> </sso> </packet>

The positive response from the server looks as follows:


<packet version="1.5.2.0"> <sso> <del-delegation-rule> <result> <status>ok</status> </result> </del-delegation-rule> </sso> </packet>

A negative response from the server can look as follows:


<packet version="1.5.2.0"> <sso> <del-delegation-rule> <result> <status>error</status> <errcode>1013</errcode> <errtext>User does not exist</errtext> </result> </del-delegation-rule> </sso> </packet>

1218

Supported Operations

Managing Subdomains
Operator: <subdomain> XML Schema: subdomain.xsd Plesk version: Plesk 8.3 for Unix and later | Plesk 8.3 for Windows and later API RPC version: 1.5.2.0 Plesk user: Plesk Administrator, Plesk client Description The subdomain operator is used to manage subdomains, both typical, and subdomains on subfolder specific to Plesk for Windows. Supported operations

ADD (on page 1222) creates a subdomain. GET (on page 1226) retrieves information on a specified subdomain from Plesk database. SET (on page 1232) changes subdomain settings. DEL (on page 1235) removes a specified subdomain. RENAME (on page 1238) renames a specified subdomain. CHANGE-PARENT (on page 1241) (supported in Plesk for Windows only) changes parent domain/subdomain for a specified subdomain on subfolder. This feature is not supported since protocol version 1.5.2.1.

Supported Operations

1219

In this section:
Filtering Issues .................................................................................................. 1219 Subdomain Properties ....................................................................................... 1220 Creating Subdomain.......................................................................................... 1222 Retrieving Information on Subdomain................................................................ 1226 Changing Subdomain Settings .......................................................................... 1232 Removing Subdomain ....................................................................................... 1235 Renaming Subdomain ....................................................................................... 1238 Changing Parent Domain .................................................................................. 1241

Filtering Issues
Filtering is the way the request XML packet indicates the object (one or several subdomains) to which the operation will be applied. Parameters nested in the filter node are called filtering rule. The filter node is presented by the SubdomainFilterType complex type (subdomain.xsd). This data type is structured as follows:

The id node is optional. It specifies subdomain ID in Plesk database. Data type: id_type. The name node is optional. It specifies full subdomain name (including parent domain name). Data type: string. The parent-name node is optional. It specifies a name of domain/subdomain on which the subdomain is created. Data type: string.

A subdomain can be filtered by either id node, name node or parent-name node. The same is true if several subdomains are filtered by their IDs, names or parent names with one filter node. However, using different nodes within the same filter node is prohibited.

1220

Supported Operations

To apply requested operation to all subdomains, use the blank (<filter/>) filter node. For example, a packet that retrieves the information about all subdomains looks as follows:
<packet version="1.5.2.0"> <subdomain> <get> <filter/> </get> </subdomain> </packet>

Subdomain Properties
Subdomain hosting properties are specified by complex type SubdomainPropertyType (subdomain.xsd). It is structured as follows:

The name node is required. It specifies a subdomain property name. Data type: string. The value node is required. It specifies a subdomain property value. Data type: anySimple.

Subdomain hosting properties are not specified in the protocol. To get a list of the available properties, use the domain/get-physical-hosting-descriptor operation. For more information on this operation, refer to Retrieving Descriptor of Hosting Settings (on page 482) section. The operation retrieves information on all properties of Plesk hosted objects in the form of Property Descriptor (on page 48). Use property extensions to filter out properties specific to subdomains or subdomains on subfolders. For more information about this extensions, refer to the section Extension of Hosting Settings Descriptor (on page 51).

Supported Operations

1221

The following packet retrieved information on subdomain photo.example.com:


<packet version="1.5.2.0"> <subdomain> <get> <result> <status>ok</status> <filter-id>photo.example.com</filter-id> <id>2</id> <data> <parent>example.com</parent> <name>photo.example.com</name> <property> <name>ssi</name> <value>false</value> </property> <property> <name>php</name> <value>false</value> </property> <property> <name>cgi</name> <value>true</value> </property> <property> <name>perl</name> <value>true</value> </property> <property> <name>python</name> <value>false</value> </property> <property> <name>asp</name> <value>true</value> </property> <property> <name>coldfusion</name> <value>false</value> </property> <property> <name>fastcgi</name> <value>false</value> </property> <property> <name>miva</name> <value>false</value> </property> <property> <name>sys_user_type</name> <value>main</value> </property> <property> <name>login</name> <value/> </property> <property> <name>passwd</name> <value/> </property>

1222

Supported Operations <property> <name>quota</name> <value/> </property> <property> <name>passwd_type</name> <value/> </property> <property> <name>displayName</name> <value>photo</value> </property> <property> <name>ssl</name> <value>false</value> </property> <property> <name>same_ssl</name> <value>false</value> </property> </data> </result> </get> </subdomain> </packet>

Creating Subdomain
Use the add operation to create a subdomain. To create a subdomain, specify a parent domain/subdomain name, the subdomain name and subdomain properties. To create a subdomain on subfolder, specify a parent domain/subdomain name, the subdomain name, a subfolder on which subdomain is created, and subdomain properties.

Note: For subdomains on subfolder, creation of a separate FTP user account is impossible: the FTP user account of a parent domain/subdomain is used.

In this section:
Request Packet Structure.................................................................................. 1223 Request Samples .............................................................................................. 1224 Response Packet Structure ............................................................................... 1225 Response Samples ........................................................................................... 1226

Supported Operations

1223

Request Packet Structure


A request XML packet adding a new subdomain to Plesk, includes the add operation node:
<packet version="1.5.2.0"> <subdomain> <add> </add> </subdomain> </packet>

The add node is presented by the SubdomainAddInputType (subdomain.xsd). Its graphical representation is as follows:

The parent node is required. It specifies a name of domain/subdomain on which a subdomain is created. (Parent subdomain is supported in Plesk for Windows only.) Data type: string. The name node is required. It specifies a name of the subdomain. Data type: string. The home node is required if the subdomain on subfolder is created. It specifies a path to a home directory of the subdomain. If the home node is left blank (<home/>), the root directory of the parent domain is used. Data type: string. The property node is required. It specifies a hosting setting of a created subdomain. To see the structure of this node, refer to the section Subdomain Properties (on page 1220). Data type: SubdomainPropertyType (subdomain.xsd).

1224

Supported Operations

Request Samples
This packet creates subdomain forum.example.com, sets FTP account credentials, sets SSI support, and enables using SSI for *.htm and *.html files on the subdomain:
<packet version="1.5.2.0"> <subdomain> <add> <parent>example.com</parent> <name>forum</name> <property> <name>ftp_login</name> <value>john</value> </property> <property> <name>ftp_password</name> <value>sample</value> </property> <property> <name>ssi</name> <value>true</value> </property> <property> <name>ssi_html</name> <value>true</value> </property> </add> </subdomain> </packet>

Creating a subdomain on subfolder This packet creates subdomain sample.example.com on subfolder /httpdocs/sample and sets Perl and CGI support on it:
<packet version="1.5.2.0"> <subdomain> <add> <parent>example.com</parent> <name>sample</name> <home>/httpdocs/sample</home> <property> <name>perl</name> <value>true</value> </property> <property> <name>cgi</name> <value>true</value> </property> </add> </subdomain> </packet>

Supported Operations

1225

Response Packet Structure


The add node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultType (common.xsd). The status node is required. It specifies the execution status of the add operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the add operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the add operation fails. It returns the error message. Data type: string. The id node is required if the add operation succeeds. It returns the ID of a created subdomain. Data type: id_type (common.xsd).

Possible Errors 1006 - Permission is denied. 1007 - Subdomain with such name already exists. 1015 - Parent domain/subdomain is not found. 1019 - Invalid property name. 1023 - Operation failed. 1034 - Subdomains are not supported on domains without physical hosting.

1226

Supported Operations

Response Samples
A positive response received from the server upon subdomain creation can look as follows:
<packet version="1.5.2.0"> <subdomain> <add> <result> <status>ok</status> <id>1</id> </result> </add> </subdomain> </packet>

A negative response can look as follows:


<packet version="1.5.2.0"> <subdomain> <add> <result> <status>error</status> <errcode>1034</errcode> <errtext>subdomains are not supported on domains without physical hosting</errtext> </result> </add> </subdomain> </packet>

Retrieving Information on Subdomain


The get operation is used to retrieve the following information on a subdomain from Plesk database: subdomain name parent domain/subdomain name home directory (for subdomain on subfolder only) hosting properties

In this section:
Request Packet Structure ..................................................................................1227 Request Samples ..............................................................................................1227 Response Packet Structure ...............................................................................1228 Response Samples ............................................................................................1230

Supported Operations

1227

Request Packet Structure


A request XML packet retrieving information on a subdomain includes the get operation node:
<packet version="1.5.2.0"> <subdomain> <get> </get> </subdomain> </packet>

The get node is presented by the SubdomainGetInputType (subdomain.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on filters, refer to the Filtering Issues (see page 491) section. Data type: SubdomainFilterType (subdomain.xsd).

Request Samples
This packet retrieves information on the subdomain forum.example.com.
<packet version="1.5.2.0"> <subdomain> <get> <filter> <name>forum.example.com</name> </filter> </get> </subdomain> </packet>

This packet retrieves information on all subdomains existing on the domain example.com.
<packet version="1.5.2.0"> <subdomain> <get> <filter> <parent-name>example.com</parent-name> </filter> </get> </subdomain> </packet>

1228

Supported Operations

This packet retrieves information on all subdomains hosting on the Plesk server.
<packet version="1.5.2.0"> <subdomain> <get> <filter/> </get> </subdomain> </packet>

Response Packet Structure


The get node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the get operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the get operation fails. It returns the error message. Data type: string. The filter-id node is required if the get operation succeeds. It returns the parameter by which the subdomain was filtered in the request packet. Data type: anySimple.

Supported Operations

1229

The id node is required if the get operation succeeds. It returns the ID of the subdomain which settings are retrieved in the response packet. Data type: id_type (common.xsd). The data node is required if the get operation succeeds. It returns a collection of requested subdomain settings. Data type: SubdomainObjectType (subdomain.xsd). See the structure of this node below.

The data node is defined by complex type SubdomainObjectType (subdomain.xsd). It is structured as follows:

The parent node is required. It returns a name of a parent domain/subdomain. Data type: string. The name node is required. It returns subdomain name. Data type: string. The home node is required if the information about a subdomain on subfolder is retrieved. It returns a path to a subdomain home directory. If the home node is left blank (<home/>), the root directory of the parent domain is used. Data type: string. The property node is required. It returns a hosting setting. To see the structure of this node, refer to the section Subdomain Properties (on page 1220). Data type: SubdomainPropertyType (subdomain.xsd).

Possible Errors 1006 - Permission is denied. 1013 - Subdomain does not exist. 1015 - Parent domain/subdomain is not found. 1023 - Operation failed.

1230

Supported Operations

Response Samples
A positive response from the server which retrieves info on a specified subdomain can look as follows:
<packet version="1.5.2.0"> <subdomain> <get> <result> <status>ok</status> <filter-id>forum.example.com</filter-id> <id>1</id> <data> <parent>example.com</parent> <name>forum.example.com</name> <property> <name>ssi</name> <value>false</value> </property> <property> <name>php</name> <value>false</value> </property> <property> <name>cgi</name> <value>false</value> </property> <property> <name>perl</name> <value>false</value> </property> <property> <name>python</name> <value>false</value> </property> <property> <name>asp</name> <value>false</value> </property> <property> <name>coldfusion</name> <value>false</value> </property> <property> <name>fastcgi</name> <value>false</value> </property> <property> <name>miva</name> <value>false</value> </property> <property> <name>sys_user_type</name> <value>main</value> </property> <property> <name>login</name> <value/> </property>

Supported Operations <property> <name>passwd</name> <value/> </property> <property> <name>quota</name> <value/> </property> <property> <name>passwd_type</name> <value/> </property> <property> <name>displayName</name> <value>forum</value> </property> <property> <name>ssl</name> <value>false</value> </property> <property> <name>same_ssl</name> <value>false</value> </property> </data> </result> </get> </subdomain> </packet>

1231

A negative response can look as follows:


<packet version="1.5.2.0"> <subdomain> <get> <result> <status>error</status> <errcode>1015</errcode> <errtext>parent domain/subdomain is not found</errtext> <filter-id>example.com</filter-id> </result> </get> </subdomain> </packet>

1232

Supported Operations

Changing Subdomain Settings


The set operation is used to change subdomain hosting settings. You can change all settings of a subdomain at once or specify particular settings.

In this section:
Request Packet Structure.................................................................................. 1232 Request Samples .............................................................................................. 1233 Response Packet Structure ............................................................................... 1233 Response Samples ........................................................................................... 1235

Request Packet Structure


A request XML packet updating a subdomain hosting settings includes the set operation node:
<packet version="1.5.2.0"> <subdomain> <set> </set> </subdomain> </packet>

The set node is presented by the SubdomainSetInputType (subdomain.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on filters, refer to the Filtering Issues (see page 491) section. Data type: SubdomainFilterType (subdomain.xsd). The property node is required. It specifies hosting property that is to be set for the subdomain. For information on the properties, refer to the Subdomain Properties (on page 1220) section. Data type: SubdomainPropertyType (subdomain.xsd).

Supported Operations

1233

Request Samples
Changing settings of a single subdomain This packet sets PHP and CGI support for the subdomain forum.example.com.
<packet version="1.5.2.0"> <subdomain> <set> <filter> <name>forum.example.com</name> </filter> <property> <name>php</name> <value>true</value> </property> <property> <name>cgi</name> <value>true</value> </property> </set> </subdomain> </packet>

Changing settings of multiple subdomains This packet sets Perl and Miva support for all subdomains on the domain example.com.
<packet version="1.5.2.0"> <subdomain> <set> <filter> <parent-name>example.com</parent-name> </filter> <property> <name>perl</name> <value>true</value> </property> <property> <name>miva</name> <value>true</value> </property> </set> </subdomain> </packet>

1234

Supported Operations

Response Packet Structure


The set node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: ResultFilterType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the set operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the set operation fails. It returns the error message. Data type: string. The filter-id node is required if the set operation succeeds. It returns the parameter by which the subdomain was filtered in the request packet. Data type: anySimple. The id node is required if the set operation succeeds. It returns the ID of the subdomain which settings are retrieved in the response packet. Data type: id_type (common.xsd).

Possible Errors 1006 - Permission is denied. 1013 - Subdomain does not exist. 1015 - Parent domain/subdomain is not found. 1019 - Invalid property name. 1023 - Operation failed.

Supported Operations

1235

Response Samples
A positive response received from the server after changing subdomain settings can look as follows:
<packet version="1.5.2.0"> <subdomain> <set> <result> <status>ok</status> <filter-id>forum.example.com</filter-id> <id>1</id> </result> </set> </subdomain> </packet>

A negative response can look as follows:


<packet version="1.5.2.0"> <subdomain> <set> <result> <status>error</status> <errcode>1019</errcode> <errtext>invalid property name</errtext> <filter-id>forum.sample.com</filter-id> </result> </set> </subdomain> </packet>

Removing Subdomain
The del operation is used to remove a subdomain from a domain/subdomain.

In this section:
Request Packet Structure.................................................................................. 1236 Request Samples .............................................................................................. 1236 Response Packet Structure ............................................................................... 1237 Response Samples ........................................................................................... 1238

1236

Supported Operations

Request Packet Structure


A request XML packet removing a subdomain from a domain/subdomain includes the del operation node:
<packet version="1.5.2.0"> <subdomain> <del> ... </del> </subdomain> </packet>

The del node is presented by the SubdomainDeleteInputType (subdomain.xsd). Its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For information on filters, refer to the Filtering Issues (see page 491) section. Data type: SubdomainFilterType (subdomain.xsd).

Request Samples
Removing a single subdomain To remove the subdomain forum.example.com:
<packet version="1.5.2.0"> <subdomain> <del> <filter> <name>forum.example.com</name> </filter> </del> </subdomain> </packet>

Removing multiple subdomains To remove subdomains with IDs in Plesk database 2, 5 and 6:
<packet version="1.5.2.0"> <subdomain> <del> <filter> <id>2</id> <id>5</id> <id>6</id> </filter> </del> </subdomain></packet>

Supported Operations

1237

Response Packet Structure


The del node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the del operation fails. It is used to return the error code. Data type: unsignedInt. The errtext node is required if the del operation fails. It is used to return the error message. Data type: string. The filter-id node is required if the del operation succeeds. It returns the filtering rule parameter. For details, refer to the Filtering Issues (on page 925) section. Data type: anySimple. The id node is required if the del operation succeeds. It returns the ID of a deleted subdomain. Data type: id_type (common.xsd).

Possible Errors 1006 - Permission is denied. 1013 - Subdomain does not exist. 1015 - Parent domain/subdomain is not found. 1023 - Operation failed.

1238

Supported Operations

Response Samples
A positive response received from the server upon removing a subdomain can look as follows:
<packet version="1.5.2.0"> <subdomain> <del> <result> <status>ok</status> <filter-id>13</filter-id> <id>13</id> </result> </del> </subdomain> </packet>

A negative response can look as follows:


<packet version="1.5.2.0"> <subdomain> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>subdomain does not exist</errtext> <filter-id>forum</filter-id> </result> </del> </subdomain> </packet>

Renaming Subdomain
The rename operation is used to change a subdomain name.

In this section:
Request Packet Structure.................................................................................. 1239 Request Samples .............................................................................................. 1239 Response Packet Structure ............................................................................... 1240 Response Samples ........................................................................................... 1241

Supported Operations

1239

Request Packet Structure


A request XML packet renaming a subdomain includes the rename operation node:
<packet version="1.5.2.0"> <subdomain> <rename> ... </rename> </subdomain> </packet>

The rename node is presented by the SubdomainRenameInputType (subdomain.xsd). Its graphical representation is as follows:

The id node is required. It specifies a subdomain ID. Data type: id_type. The name node is required. It specifies a new name of the subdomain (without parent domain name). Data type: string.

Request Samples
To rename a subdomain with ID 3 to forum:
<packet version="1.5.2.0"> <subdomain> <rename> <id>3</id> <name>forum</name> </rename> </subdomain> </packet>

1240

Supported Operations

Response Packet Structure


The rename node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the rename operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errcode node is required if the rename operation fails. It is used to return the error code. Data type: unsignedInt. The errtext node is required if the rename operation fails. It is used to return the error message. Data type: string.

Possible Errors 1007 - Subdomain with such name already exists. 1013 - Subdomain with such ID is absent. 1023 - Operation failed.

Supported Operations

1241

Response Samples
A positive response received from the server upon renaming a subdomain looks as follows:
<packet version="1.5.2.0"> <subdomain> <rename> <result> <status>ok</status> </result> </rename> </subdomain> </packet>

A negative response can look as follows:


<packet version="1.5.2.0"> <subdomain> <rename> <result> <status>error</status> <errcode>1013</errcode> <errtext>Subdomain with such id is absent</errtext> </result> </rename> </subdomain> </packet>

Changing Parent Domain


The change-parent operation is used to change a parent domain/subdomain of a specified subdomain on subfolder. This operation can be applied only within one domain, in other words, it is impossible to, for example, change subdomain location from one domain to a subdomain on another domain. Note: This operation is not supported since protocol version 1.5.2.1.

In this section:
Request Packet Structure.................................................................................. 1242 Request Samples .............................................................................................. 1242 Response Packet Structure ............................................................................... 1243 Response Samples ........................................................................................... 1244

1242

Supported Operations

Request Packet Structure


A request XML packet changing a parent domain/subdomain of a subdomain includes the change-parent operation node:
<packet version="1.5.2.0"> <subdomain> <change-parent> ... </change-parent> </subdomain> </packet>

The change-parent node is presented by the SubdomainChangeParentType (subdomain.xsd). Its graphical representation is as follows:

The id node is required. It specifies a subdomain ID. Data type: id_type (common.xsd). The parent-name is required. It specifies a parent domain/subdomain name. Data type: string.

Request Samples
This packet changes the parent subdomain of the subdomain on subfolder with ID 14 to sample.example.com:
<packet version="1.5.2.0"> <subdomain> <change-parent> <id>14</id> <parent-name>sample.example.com</parent-name> </change-parent> </subdomain> </packet>

Supported Operations

1243

Response Packet Structure


The change-parent node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the change-parent operation. Data type: result_status (common.xsd). Allowed values: ok|error. The errocode node is required if the change-parent operation fails. It returns the error code. Data type: unsignedInt. The errtext node is required if the change-parent operation fails. It returns the error message. Data type: string.

Possible Errors 1007 - Subdomain with such name already exists. 1013 - Subdomain does not exist. 1015 - Parent domain/subdomain is not found. 1023 - Operation failed.

1244

Supported Operations

Response Samples
A positive response received from the server upon changing a parent domain/subdomain of a subdomain looks as follows:
<subdomain> <change-parent> <result> <status>ok</status> </result> </change-parent> </subdomain>

A negative response can look as follows:


<subdomain> <change-parent> <result> <status>error</status> <errcode>1007</errcode> <errtext>subdomain with such name already exists</errtext> </result> </change-parent> </subdomain>

Supported Operations

1245

Managing User Interface


Operator: <ui> XML Schema: ui_input.xsd, ui_output.xsd, plesk_custom_buttons.xsd Plesk version: Plesk 7.5.3 for Unix and later | Plesk 7.5 for Windows API RPC version: 1.3.5.0 and higher Plesk user: Plesk Administrator

Description A custom button is a shortcut to Plesk Web application or to an external or internal web page. It consists of an icon and a hyperlink. The ui operator serves for managing custom buttons. The operator also allows Plesk Administrators to customize graphical user interface of Plesk, so that Administrator defines what controls buttons, icons, options and so on should be visible or not to which Plesk users. Supported operations:

SET_VISIBILITY_CUSTOMIZATIONS (on page 1246) sets up user-oriented visibility options for a specified GUI control in Plesk CREATE-CUSTOMBUTTON (on page 1255) creates custom button either bound or not bound to a Web application GET-CUSTOMBUTTON (on page 1260) gets information about the specified custom button(s) from the Plesk database DELETE-CUSTOMBUTTON (on page 1264) removes the specified custom button(s) from Control Panel and the Plesk database

1246

Supported Operations

In this section:
Setting Up Controls Visibility ............................................................................. 1246 Managing Custom Buttons ................................................................................ 1249

Setting Up Controls Visibility


The set_visibility_customizations operation is used to configure Plesk interface.

In this section:
Request Packet Structure.................................................................................. 1246 Request Samples .............................................................................................. 1247 Response Packet Structure ............................................................................... 1248 Response Samples ........................................................................................... 1249

Request Packet Structure


Request Packet Structure A request XML packet setting up control's visibility options contains the set_visibility_customizations operation node:
<packet version="1.4.2.0"> <ui> <set_visibility_customizations> ... </set_visibility_customizations> </ui> </packet>

The set_visibility_customizations node is structured as follows:

The page_id node is required. It specifies the unique identifier of the Plesk page where the required control is placed. Data type: string. The control_id node is required. It specifies the ID of the control which visibility options are set up. Data type: string.

Supported Operations

1247

The visibility node is required. It specifies what visibility option should be applied to the control. Data type: string. Allowed values: hide (= "hide the control from all Plesk users including Administrator") | show (= "show the control to all Plesk users") | adminOnly (= "hide the control from all Plesk users excluding Administrator"). The control node is required. It defines the type of the control specified by the control_id node. Data type: string. Allowed values: button (= "the control is a button") | formControl (= "the control is a checkbox, radio button, drop-down list, etc.").

Request Samples
This packet hides from all Plesk users excluding Administrator the SSH Terminal button located on domain management pages.
<packet version="1.4.2.0"> <ui> <set_visibility_customizations> <page_id>domains/dom_ctrl</page_id> <control_id>sshterm</control_id> <visibility>hide</visibility> <control>button</control> </set_visibility_customizations> </ui> </packet>

This packet hides from Plesk users excluding Administrator the Enable webuser@domain_name access format checkbox located at Plesk page Domains > domain_name > Web users > Preferences.
<packet version="1.4.2.0"> <ui> <set_visibility_customizations> <page_id>domains/dom_users/dl_usr_ed</page_id> <control_id>manage_spamfilter</control_id> <visibility>adminOnly</visibility> <control>formControl</control> </set_visibility_customizations> </ui> </packet>

1248

Supported Operations

Response Packet Structure


The set_visibility_customizations node of the response XML packets is structured as follows:

The result node is required. It wraps the result of the set_visibility_customizations operation. Data type: resultType (common.xsd). The status node is required. It returns the execution status of the set_visibility_customizations operation. Data type: result_status (common.xsd). Allowed values: ok | error. The errcode node is optional. It returns the error code when the set_visibility_customizations operation fails. Data type: unsignedInt (integer). The errtext node is optional. It returns the error message if the set_visibility_customizations operation fails. Data type: string.

Supported Operations

1249

Response Samples
This request packet hides from all Plesk users excluding Administrator the SSH Terminal button located on domain management pages.
<packet version="1.4.2.0"> <ui> <set_visibility_customizations> <page_id>domains/dom_ctrl</page_id> <control_id>sshterm</control_id> <visibility>hide</visibility> <control>button</control> </set_visibility_customizations> </ui> </packet>

If the button was not found, the response looks as follows:


<packet version="1.5.0.0"> <ui> <set_visibility_customizations> <result> <status>error</status> <errcode>1013</errcode> <errtext>Control does not exist</errtext> </result> </set_visibility_customizations> </ui> </packet>

Managing Custom Buttons


You can manage buttons your customers will see it in their control panels. This can be a link to an application, external or internal web page. The link can optionally contain your parameters (client ID, domain ID) used for processing by applications.

In this section:
Custom Button Settings ..................................................................................... 1250 Filtering Issues .................................................................................................. 1254 Creating Custom Buttons .................................................................................. 1255 Retrieving Custom Button Settings .................................................................... 1260 Removing Custom Buttons ................................................................................ 1264

1250

Supported Operations

Custom Button Settings


Settings of a custom button can be divided into three groups: Owner settings (on page 1250). These settings define users who can manage the custom button. Permissions from Plesk business login work here as well. Custom button properties (on page 1251). These settings define what the button will do, where it will be located and for whom it will be visible. URL Components (on page 1253). These settings define data that will be added to the URL specified in the button's properties. Use it to send parameters via the GET method to external web applications.

In this section:
Owner ................................................................................................................1250 Properties ..........................................................................................................1251 URL Components ..............................................................................................1253

Owner
The settings are defined by type CBOwner (plesk_custom_button.xsd). The graphical representation of the type is as follows:

The admin node is required. It specifies if a custom button belongs to Plesk Administrator. Data type: none. The client-id node is required. It specifies ID of the client who owns the custom button. Data type: integer. The domain-id node is required. It specifies ID of the domain administrator who owns the custom button. Data type: integer.

Supported Operations

1251

Properties
A custom button can point to a web page or to a Web application. Properties of these two kinds of buttons are slightly different.

In this section:
Hyperlinks to Web applications ......................................................................... 1251 Hyperlinks to Web Applications ......................................................................... 1252

Hyperlinks to Web applications


The settings are defined by type CBProps (plesk_custom_button.xsd). The graphical representation of the type is as follows:

The sort_key node is optional. It specifies the priority of the button. In Plesk, custom buttons are arranged in accordance with the priority you define: the lower the number the higher is priority. Buttons are placed in the left-to-right order. Data type: integer. The conhelp node is optional. It specifies text that appears when mouse cursor is over the button. If not specified, the text node value will be set as the conhelp value. Data type: string. The file node is optional. It specifies location of the image file linked to the custom button. Data type: string. The public node is optional. It specifies if the button is visible to all sub-users (according to Plesk business logic) of the owner. Data type: boolean. The internal node is optional. It defines if the URL is opened in the right Plesk frame or in the new window. Data type: boolean. The place node is required. It specifies location of the button. Data type: string. Allowed values: client | domain | admin | navigation.

1252

Supported Operations

client. The button is placed on each client's home page or desktop. domain. The button is placed on each domain owner's home page or desktop. admin. The button is placed on each administrator's home page or desktop navigation. The button is placed in the navigation pane.

The url node is required. It specifies the hyperlink to be attached to the button. data type: string. The text node is required. It specifies a label for the custom button. Data type: string.

Hyperlinks to Web Applications


The settings are defined by type CBOptionalProps (plesk_custom_button.xsd). The graphical representation of the type is as follows:

The sort_key node is optional. It specifies the priority of the button. In Plesk, custom buttons are arranged in accordance with the priority you define: the lower the number the higher is priority. Buttons are placed in the left-to-right order. Data type: integer. The conhelp node is optional. It specifies text that appears when mouse cursor is over the button. If not specified, the text node value will be set as the conhelp value. Data type: string. The file node is optional. It specifies location of the image file linked to the custom button. Data type: string. The public node is optional. It specifies if the button is visible to all sub-users (according to Plesk business logic) of the owner. Data type: boolean. The internal node is optional. It defines if the URL is opened in the right Plesk frame or in the new window. Data type: boolean.

Supported Operations

1253

URL Components
The settings are defined by type CBUrlComponents (plesk_custom_button.xsd). The graphical representation of the type is as follows:

The dom_id node is optional. It specifies if domain ID is included in the URL. Data type: boolean. The dom_name node is optional. It specifies if the domain name is included in the URL. Data type: boolean. The ftp_user node is optional. It specifies if the FTP login name is included in the URL. Data type: boolean. The ftp_pass node is optional. It specifies if the FTP password is included in the URL. Data type: boolean. The cl_id node is optional. It specifies if the client ID is included in the URL. Data type: boolean. The cname node is optional. It specifies if the client name is included in the URL. Data type: boolean. The pname node is optional. It specifies if the full name of a person who clicks the button is included in the URL. Data type: boolean. The email node is optional. It specifies if the e-mail address of a person who clicks the button is included in the URL.. Data type: string.

1254

Supported Operations

Filtering Issues
Filtering is the way the request XML packet indicates the object (a custom button or several) to which the operation will be applied. The request XML packet filters custom buttons using a special filter node. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule.

In this section:
customButtonFilter ............................................................................................ 1254

customButtonFilter
The filter for this operator is presented by type customButtonFilter (ui_input.xsd) and structured as follows:

The custombutton-id node is required. It specifies ID of a custom button. Data type: integer. The owner node is required. It specifies the custom button owner. For details, refer to the Owner (on page 1250) section. Data type: CBOwner (plesk_custom_button.xsd).

Supported Operations

1255

Remarks A single filtering rule can specify multiple custombutton-id or owner parameters. The filter that matches custom buttons with ID 4 and 5 looks as follows:
<filter> <custombutton-id>4</custombutton-id> <custombutton-id>4</custombutton-id> </filter>

The filter that matches custom buttons owned by clients with ID 1 and 2 looks as follows:
<filter> <owner> <client-id>1</client-id> </owner> <owner> <client-id>2</client-id> </owner> </filter>

Creating Custom Buttons


The create-custombutton operation is used to create custom buttons.

In this section:
Request Packet Structure.................................................................................. 1255 Request Samples .............................................................................................. 1257 Response Packet Structure ............................................................................... 1258 Response Samples ........................................................................................... 1259

Request Packet Structure


A request XML packet creating a custom button includes the create-custombutton operation node:
<packet version="1.5.1.0"> <ui> <create-custombutton> <set> </set> </create-custombutton> </ui> </packet>

1256

Supported Operations

The create-custombutton node graphical representation is as follows:

To create a custom button for web applications, set values for the following nodes: The owner node is required. It specifies users who can manage the custom button. For more information, refer to the Owner (on page 1250) section. Data type: CBOwner (plesk_custom_button.xsd). The properties node is required. It specifies behavior of the button. For details, refer to the Properties (on page 1251) section. Data type: CBProps (plesk_custom_button.xsd). The uri-components node is optional. It specifies parameters that are sent via the GET method to external web applications when clicking the button. Data type: CBUrlComponents (plesk_custom_button.xsd).

To create a custom button for Web applications, set values for the following nodes: The siteapp-id node is required. It specifies the ID of a Web application. Data type: string. The optional-properties node is optional. It specifies behavior of the button. For details, refer to the Properties (on page 1252) section. Data type: CBOptionalProps (plesk_custom_button.xsd).

Supported Operations

1257

Request Samples
The following packet creates a custom button and adds it to the custom buttons list of the client with ID 12.
<packet version="1.5.1.0"> <ui> <create-custombutton> <owner> <client-id>12</client-id> </owner> <properties> <place>client</place> <url>http://example.com</url> <text>Example domain</text> </properties> </create-custombutton> </ui> </packet>

The following packet creates a custom button and adds it to the custom buttons list of Plesk Administrator. The button URL contains contact name of the Administrator and his e-mail address.
<packet version="1.5.1.0"> <ui> <create-custombutton> <owner> <admin/> </owner> <properties> <place>admin</place> <url>http://example.com</url> <text>Example domain</text> </properties> <url-components> <pname/> <email/> </url-components> </create-custombutton> </ui> </packet>

1258

Supported Operations

Response Packet Structure


The create-custombutton node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The id node is optional. If the operation succeeds, it returns the ID of the created custom button. Data type: integer.

Supported Operations

1259

Response Samples
The following packet creates a custom button and adds it to the custom buttons list of the client with ID 12.
<packet version="1.5.1.0"> <ui> <create-custombutton> <owner> <client-id>12</client-id> </owner> <properties> <place>client</place> <url>http://example.com</url> <text>Example domain</text> </properties> </create-custombutton> </ui> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <ui> <create-custombutton> <result> <status>ok</status> <id>4</id> </result> </create-custombutton> </ui> </packet>

A positive response from the server can look as follows:


<packet version="1.5.0.0"> <ui> <create-custombutton> <result> <status>error</status> <errcode>1013</errcode> <errtext>The client does not exist</errtext> </result> </create-custombutton> </ui> </packet>

1260

Supported Operations

Retrieving Custom Button Settings


The get-custombutton operation is used to retrieve custom button settings.

In this section:
Request Packet Structure.................................................................................. 1260 Request Samples .............................................................................................. 1260 Response Packet Structure ............................................................................... 1261 Response Samples ........................................................................................... 1263

Request Packet Structure


A request XML packet retrieving a custom button settings includes the get-custombutton operation node:
<packet version="1.5.1.0"> <ui> <get-custombutton> </get-custombutton> </ui> </packet>

The get-custombutton graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: customButtonFilter (ui_input.xsd).

Supported Operations

1261

Request Samples
The following packet retrieves settings of custom buttons of the client with ID 1.
<packet version="1.5.1.0"> <ui> <get-custombutton> <filter> <owner> <client-id>1</client-id> </owner> </filter> </get-custombutton> </ui> </packet>

The following packet retrieves settings of custom button with ID 1.


<packet version="1.5.1.0"> <ui> <get-custombutton> <filter> <custombutton-id>1</custombutton-id> </filter> </get-custombutton> </ui> </packet>

1262

Supported Operations

Response Packet Structure


The get-custombutton node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The id node is optional. If the operation succeeds, it returns the ID of the custom button. Data type: integer. The owner node is required. It specifies users who can manage the custom button. For more information, refer to the Owner (on page 1250) section. Data type: CBOwner (plesk_custom_button.xsd). The properties node is required. It specifies behavior of the button. For details, refer to the Properties (on page 1251) section. Data type: CBProps (plesk_custom_button.xsd).

Note: When you retrieve details on the custom button that links to a Web application, and you have not specified values for all required properties nodes, the validation error occurs.

Supported Operations

1263

The uri-components node is optional. It specifies parameters that are sent via the GET method to external web applications when clicking the button. Data type: CBUrlComponents (plesk_custom_button.xsd).

Response Samples
The following packet retrieves settings of custom button with ID 1.
<packet version="1.5.1.0"> <ui> <get-custombutton> <filter> <custombutton-id>1</custombutton-id> </filter> </get-custombutton> </ui> </packet>

A positive response from the server can look as follows:


<packet version="1.5.1.0"> <ui> <get-custombutton> <result> <status>ok</status> <id>1</id> <owner>admin</owner> <properties> <place>admin</place> <url>http://example.com</url> <text>Example domain</text> </properties> <url-components/> </result> </get-custombutton> </ui> </packet>

1264

Supported Operations

Removing Custom Buttons


The delete-custombutton operation is used to remove custom buttons.

In this section:
Request Packet Structure.................................................................................. 1264 Request Samples .............................................................................................. 1264 Response Packet Structure ............................................................................... 1265 Response Samples ........................................................................................... 1266

Request Packet Structure


A request XML packet removing a custom button includes the delete-custombutton operation node:
<packet version="1.5.1.0"> <ui> <delete-custombutton> </delete-custombutton> </ui> </packet>

The delete-custombutton graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (on page 606) section. Data type: customButtonFilter (ui_input.xsd).

Request Samples
The following packet removes custom buttons of the client with ID 1.
<packet version="1.5.1.0"> <ui> <delete-custombutton> <filter> <owner> <client-id>1</client-id> </owner> </filter> </delete-custombutton> </ui> </packet>

Supported Operations

1265

The following packet removes custom button with ID 1.


<packet version="1.5.1.0"> <ui> <delete-custombutton> <filter> <custombutton-id>1</custombutton-id> </filter> </delete-custombutton> </ui> </packet>

Response Packet Structure


The delete-custombutton node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the operation fails. Data type: integer. The errtext node is optional. It returns the error message if the operation fails. Data type: string. The id node is optional. If the operation succeeds, it returns the ID of the removed custom button. Data type: integer.

1266

Supported Operations

Response Samples
The following packet removes custom button with ID 1.
<packet version="1.5.1.0"> <ui> <delete-custombutton> <filter> <custombutton-id>1</custombutton-id> </filter> </delete-custombutton> </ui> </packet>

A positive response from the server looks as follows:


<packet version="1.5.1.0"> <ui> <delete-custombutton> <result> <status>ok</status> <id>1</id> </result> </delete-custombutton> </ui> </packet>

The following packet removes custom buttons of the client with ID 2.


<packet version="1.5.1.0"> <ui> <delete-custombutton> <filter> <owner> <client-id>2</client-id> </owner> </filter> </delete-custombutton> </ui> </packet>

A positive response from the server can look as follows:


<packet version="1.5.1.0"> <ui> <delete-custombutton> <result> <status>ok</status> <id>1</id> </result> <result> <status>ok</status> <id>2</id> </result> <result> <status>ok</status> <id>3</id> </result> </delete-custombutton></ui></packet>

Supported Operations

1267

Managing Virtual Directories


Operator: <virtdir> XML Schema: virtdir.xsd Plesk version: Plesk 7.6.1 for Windows and later API RPC version: 1.4.1.1 and higher Plesk user: Plesk Administrator Description Virtual directories are supported in Plesk 7.6.1 (and later) for Windows only. In brief, this feature provides customers with the opportunity to map the contents of a definite physical folder of the site to a virtual directory (which is being created at that moment). The resulting virtual directory becomes an independent item, and obtains various settings, including access permissions, properties of a web application, SSL support, logging, and others. Virtual directories can be created for an existing physical directory of the site. The path of this physical directory is specified in the create command sent to Plesk. If the specified directory does not exist, it will be created on the virtual host by the specified path. Supported operations:

CREATE (see page 1275) creates a virtual directory for the specified physical directory REMOVE (see page 1280) deletes a virtual directory

All operations are performed by sending XML packets with the <virtdir> operator (defined in virtdir.xsd).

In this section:
Virtual Directory Settings ................................................................................... 1268 Creating Virtual Directories................................................................................ 1275 Removing Virtual Directories ............................................................................. 1280

1268

Supported Operations

Virtual Directory Settings


The virtual directory settings can be set when creating a virtual directory. They are as follows: Virtual directory properties (see page 1268) are used to set up access rights Web application properties (see page 1271) are used to enable/disable web application mode for the virtual directory Default page properties (see page 1273) are used to enable/disable displaying default page for the virtual directory

In this section:
Virtual Directory Properties................................................................................ 1268 Web Application Properties ............................................................................... 1271 Default Page Properties .................................................................................... 1273

Supported Operations

1269

Virtual Directory Properties


Virtual directory properties are specified by the properties node. This node is presented by type VDirProperties (virtdir.xsd). It has the following graphics model:

The real-path node is optional. It specifies the path of the physical directory mapped by the virtual directory. The path is specified relative to the root directory of the domain that owns this physical directory. If the specified physical folder does not exist, it will be created. Data type: RealDirPath (virtdir.xsd). Default value: / .

Note: in API RPC v.1.4.2.0 and earlier versions, the type of this node is VDirPath (virtdir.xsd). The access-source node is optional. Enables or disables user access to the source code of ASP applications (residing within the specified virtual directory and its nonvirtual subfolders) with read or write permissions (if set). Data type: Boolean. Default value: false. The access-read node is optional. Enables or disables read access to files located within the specified virtual directory. Data type: boolean. Default value: true.

1270

Supported Operations

The access-write node is optional. Enables or disables write access to files located within the specified virtual directory. Data type: boolean. Default value: false. The dir-browsing node is optional. Allows or disallows the user to see files and nested directories of the specified virtual directory in the browser. Data type: boolean. Default value: false. The log-visits node is optional. Enables or disables logging the information about visiting the virtual directory. Data type: Boolean. Default value: true. The application node is optional. Specifies a collection of properties used to specify a virtual directory as a web application and configure its execution by the web server. Data type: VDirAppType (virtdir.xsd). To see the structure of this node, proceed to the Web Application Properties (see page 1271) topic. The execute-perm node is optional. Specifies execution permissions for files located within the specified virtual directory. Data type: VDirExecutePermissionsType (virtdir.xsd). Allowed values: none (only static files can be displayed) | script (static files can be displayed, scripts can be executed) | script_execute (all files can be executed). Default value: script. The default-doc node is optional. Specifies a collection of default page properties. These properties enable or disable display of a default page when the user visits the virtual directory with no particular file name specified. Data type: VDirDefaultDocType (virtdir.xsd). To see the structure of this node, proceed to the Default Page Properties (see page 1273) section. The access-anonymous node is optional. Enables or disables public access to the virtual directory. Data type: boolean. If set to true, indicates that the user can access the directory without authentication. The require-ssl node is optional. Enables or disables SSL access to the virtual directory. Data type: boolean. The asp-buffering-limit node is optional. Limits the size (in KB) of ASP buffer assigned to a specified virtual directory. Data type: int. Available since protocol version 1.5.2.0. The asp-max-request-entity-allowed node is optional. Limits the size (in KB) of ASP request entity body. Data type: int. Available since protocol version 1.5.2.0. The asp-enabled-server-debug node is optional. Enables or disables ASP server-side script debugging. If it is a root directory, default value is defined by IIS; else inherited by parent directory. Data type: Boolean. Available since protocol version 1.5.2.0. The asp-enablde-client-debug node is optional. Enables or disables ASP client-side script debugging. If it is a root directory, default value is defined by IIS; else inherited by parent directory. Data type: Boolean. Available since protocol version 1.5.2.0.

The following sample packet creates a virtual directory and specifies main properties for it:
<packet version="1.5.2.0"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties> <real-path>/real_dir</real-path>

Supported Operations <access-source>true</access-source> <access-read>true</access-read> <access-write>true</access-write> <dir-browsing>true</dir-browsing> <log-visits>true</log-visits> <execute-perm>none</execute-perm> <access-anonymous>true</access-anonymous> <require-ssl>true</require-ssl> <asp-buffering-limit>1024</asp-buffering-limit> <asp-enabled-server-debug>true</asp-enabled-server-debug> </properties> </create> </virtdir> </packet>

1271

Web Application Properties


To make the web server use a virtual directory as a web application, it is necessary to define web application properties for this virtual directory. The application node serves for this purpose. This node is presented by type VDirAppType (virtdir.xsd). It has the following graphics model:

The enabled node is required. If set to true, it enables the virtual directory to function as a web application. Data type: Boolean. The parent-paths node is optional. If set to true, active scripts of the virtual directory are allowed to access its parent directories by relative paths (using the .. syntax). Data type: Boolean. Default value: false. If this feature is enabled, it is recommended that the execute_perm node holds none. The run-in-mta node is required. Enables or disables the web application (located in the virtual directory) to run in the multithreaded apartment (MTA). Data type: Boolean. Default value: false. The aspnet-version is optional. Specifies the ASP.NET version for web applications located in the virtual directory. Data type: string. Allowed values: 1.1 | 2.0. The disabled node is required. If set to true, it disables the virtual directory to function as a web application. Data type: Boolean.

1272

Supported Operations

The following sample packet creates a virtual directory and defines it as a web application:
<packet version="1.4.1.1"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties> <require-ssl>true</require-ssl> <application> <enabled/> <parent-paths>true</parent-paths> <run-in-mta>true</run-in-mta> <aspnet-version>1.1</aspnet-version> </application> <execute-perm>none</execute-perm> </properties> </create> </virtdir> </packet>

The following packet creates a virtual directory and sets the disabled web application mode for it:
<packet version="1.4.1.1"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties> <require-ssl>true</require-ssl> <application> <disabled/> </application> </properties> </create> </virtdir> </packet>

Supported Operations

1273

Default Page Properties


The default-doc node is used to enable or disable displaying the default page when the user visits the virtual directory with no particular file name specified. This node is defined by data type VDirDefaultDocType (virtdir.xsd). It is structured as follows:

The enabled node is required. If set to true, enables the display of the default page when the user visits the virtual directory. Data type: boolean. The search node is optional. Specifies the list of default HTML pages in the order they are searched in the virtual directory. The first match is displayed. Data type: string. The disabled node is required. If set to true, disables the display of the default page for the virtual directory. In combination with the dir_browsing node set to true, forces the display of all nested files and directories in FTP style. If dir_browsing is false, the "Access forbidden" message is displayed.

The following sample packet creates a virtual directory, enables the display of the default page for it, and specifies the list of HTML files that can serve as default pages if found in the virtual directory:
<packet version="1.4.1.1"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties> <default-doc> <enabled/> <search>index.html</search> <search>main.html</search> <search>default.html</search> </default-doc> </properties> </create> </virtdir> </packet>

1274

Supported Operations

The following packet disables the display of a default page but enables the display of all files located in the virtual directory in the FTP style:
<packet version="1.4.1.1"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties> <dir-browsing>true</dir-browsing> <default-doc> <disabled/> </default-doc> </properties> </create> </virtdir> </packet>

The following packet creates a virtual directory and disables access to it via the browser:
<packet version="1.4.1.1"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties> <dir-browsing>false</dir-browsing> <default-doc> <disabled/> </default-doc> </properties> </create> </virtdir> </packet>

Supported Operations

1275

Creating Virtual Directories


A virtual directory can be created by Plesk Administrator only. A virtual directory is created to map an existing physical directory of the site hosted on the specified domain. The name of the virtual directory is specified as a relative path of this physical directory (the details follow). A virtual directory obtains a collection of useful features (virtual directory settings) as follows: Virtual directory properties are a collection of common settings (access, logging, or others) Web application properties are specified to make the web server manages the virtual directory as a web application Default page properties (see page 1273) specify the display a default page when the virtual directory is accessed by default (no particular page is specified)

If not specified, the default virtual directory settings will be set up. See the Virtual Directory Settings (see page 1268) section for details. You can create one to many virtual directories with a single packet, including multiple virtual directories for the same physical directory. If the specified virtual directory maps a non-existing physical one, it will be created on the virtual host. Mapping Issues Assume that we have a domain named mydomain and want to map the site hosted on this domain. We can create a virtual directory with the specified name (e.g. /vd1), and it will map the root directory of the site (...\vhost\mydomain\httpdocs). In addition, we can create more virtual directories within the created one (e.g. /vd1/vd2). This operation will create a physical directory of the same name (vd2) within the root of the site (...\vhost\mydomain\httpdocs\vd2), and this virtual directory will map the new physical one. The following table demonstrates how the specified name of the virtual directory affects the mapping:
Virtual directory name / /vd1 /vd1/vd2 The mapped physical folder ...\vhost\mydomain Comment It maps the root of the domain.

...\vhost\mydomain\httpdo It maps the root of the site hosted on cs the domain. ...\vhost\mydomain\httpdo The /vd2 virtual directory is nested cs\vd2 within the /vd1 one. Creating /vd2 means the creation of the /vd2 physical folder within \vhost\mydomain\httpdocs mapped by /vd1.

1276

Supported Operations

In this section:
Request Packet Structure.................................................................................. 1276 Request Samples .............................................................................................. 1277 Response Packet Structure ............................................................................... 1278 Response Samples ........................................................................................... 1279

Request Packet Structure


A request XML packet that creates a virtual directory should include the create operation node:
<packet version="1.4.1.1"> <virtdir> <create> ... </create> </virtdir> </packet>

The create node is presented by type CreateVDirInputType (virtdir.xsd). Its graphical representation is as follows:

The domain-id node is required. It holds the identifier of the domain that owns the virtual directory. Data type: integer. The subdomain-id node is required. it holds the identifier of the sub-domain that owns the virtual directory. Data type: integer. The name node is required. It holds the name of the virtual directory. Data type: VDirPath (common.xsd). The properties node is required. It holds a collection of virtual domain settings. Data type: VDirProperties (virtdir.xsd). To see the structure of this node, refer to the Virtual Directory Properties (see page 1268) section.

Supported Operations

1277

Request Samples
The following request packet creates a virtual directory with default properties on the specified domain:
<packet version="1.4.1.1"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties/> </create> </virtdir> </packet>

To create multiple virtual directories with a single packet, use a different create section for each:
<packet version="1.4.2.0"> <virtdir> <create> <domain-id>1</domain-id> <name>/my_vdir</name> <properties/> </create> <create> <domain-id>2</domain-id> <name>/my_vdir</name> <properties/> </create> </virtdir> </packet>

1278

Supported Operations

Response Packet Structure


The create node of the output XML packet is structured as follows:

The result node is required. It wraps the result of the create operation. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the create operation. Data type: string. Allowed values: ok|error. The errcode node is optional. Is required if the create operation fails. Returns the error code. Data type: unsignedInt. The errtext node is optional. Can be returned if the create operation fails. Returns the error message. Data type: string.

Supported Operations

1279

Response Samples
The following response packet returns after the virtual directory has been created successfully:
<packet version="1.4.2.0"> <virtdir> <create> <result> <status>ok</status> </result> </create> </virtdir> </packet>

If the request packet creates multiple virtual directories, the result of each create operation will be returned in a different create section:
<packet version="1.4.2.0"> <virtdir> <create> <result> <status>ok</status> </result> </create> <create> <result> <status>ok</status> </result> </create> </virtdir> </packet>

The create nodes will follow one another in the order they have been sent within the request packet. If the create operation fails, the following response packet can be returned by Plesk server:
<packet version="1.4.2.0"> <virtdir> <create> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </create> </virtdir> </packet>

1280

Supported Operations

Removing Virtual Directories


Use the remove operation to remove a virtual directory.

In this section:
Request Packet Structure.................................................................................. 1280 Request Samples .............................................................................................. 1281 Response Packet Structure ............................................................................... 1282 Response Samples ........................................................................................... 1283

Request Packet Structure


A request XML packet that deletes a virtual directory should include the remove operation node:
<packet version=1.4.2.0> <virtdir> <remove> </remove> </virtdir> </packet>

The remove node is presented by type RemoveVDirInputType (virtdir.xsd). Its graphical representation is as follows:

The domain-id node is required. It holds the identifier of the domain that owns the virtual directory. Data type: integer. The subdomain-id node is required. it holds the identifier of the subdomain that owns the virtual directory. Data type: integer. The name node is required. It holds the name of the virtual directory. Data type: VDirPath (common.xsd).

Supported Operations

1281

Request Samples
The following packet deletes a virtual directory with the specified name from the virtual host (domain):
<packet version="1.4.1.1"> <virtdir> <remove> <domain-id>1</domain-id> <name>/my_vdir</name> </remove> </virtdir> </packet>

To delete multiple virtual directories with a single packet, use multiple remove sections:
<packet version="1.4.2.0"> <virtdir> <remove> <domain-id>1</domain-id> <name>/my_vdir</name> </remove> <remove> <domain-id>2</domain-id> <name>/my_vdir</name> </remove> </virtdir> </packet>

1282

Supported Operations

Response Packet Structure


The remove node of the output XML packet is structured as follows:

: The result node is required. It wraps the result of the remove operation. Data type: resultType (common.xsd). The status node is required. Specifies the execution status of the remove operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is required if the remove operation fails. Returns the error code. Data type: unsignedInt. The errtext node is optional. Can be returned if the remove operation fails. Returns the error message. Data type: string.

Supported Operations

1283

Response Samples
The following response packet returns after the virtual directory has been removed successfully:
<packet version="1.4.2.0"> <virtdir> <remove> <result> <status>ok</status> </result> </remove> </virtdir> </packet>

If the request packet deletes multiple virtual directories, the result of each remove operation will be returned in a different remove section:
<packet version="1.4.2.0"> <virtdir> <remove> <result> <status>ok</status> </result> </remove> <remove> <result> <status>ok</status> </result> </remove> </virtdir> </packet>

The remove sections will follow one another in the order they have been sent within the request packet. If the remove operation fails, the following response packet can be returned by Plesk server:
<packet version="1.4.2.0"> <virtdir> <remove> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </remove> </virtdir> </packet>

1284

Supported Operations

Managing Web Users


Operator: <webuser> XML Schema: webuser.xsd Plesk version: Plesk 8.1 Win | Unix 8.1 and later API RPC version: 1.4.2.0 and higher Plesk user: Plesk Administrator, Plesk client Description Operator webuser manages web user accounts on your domain. Web users can keep static or dynamic web content with limited or unlimited allowed space on the server. These pages usually have web addresses like http://yourdomain.com/~username, however, for versions API RPC earlier 1.5.2.0, you can set up personal web pages with alternative web addresses like http://username@your-domain.com if you like. Supported operations:

ADD (see page 1291) creates a web user for a specified domain DEL (see page 1296) removes web users specified by ID or name, or deletes all web users from the domain specified by ID or name SET (see page 1302) updates settings of the web user specified by ID, name or related to a certain domain GET (see page 1308) retrieves specified web user settings from the domain SET-PREFS (see page 1319) updates web user settings for the specified domain GET-PREFS (see page 1314) retrieves web user settings for the specified domain

Supported Operations

1285

In this section:
Web User Settings and Preferences ................................................................. 1285 Filtering Issues .................................................................................................. 1289 Creating Web Users .......................................................................................... 1291 Deleting Web Users .......................................................................................... 1296 Updating Web User Settings ............................................................................. 1302 Retrieving Web Users Settings ......................................................................... 1308 Retrieving Web Users Preferences ................................................................... 1314 Updating Web Users Preferences ..................................................................... 1319

Web User Settings and Preferences


Starting from API RPC 1.5.0.0. there are two possible ways of retrieving web user settings. In API RPC v.1.4.2.0 and earlier, web user services are parameterdependable. In other protocol versions, they are parameter-undependable. Web user preferences are not affected by this variation of approaches.

In this section:
Settings ............................................................................................................. 1285 Preferences ....................................................................................................... 1288

Settings
In this section:
API RPC v.1.5.0.0 and Later Versions............................................................... 1286 API RPC v.1.4.2.0 and Earlier Versions ............................................................ 1287

1286

Supported Operations

API RPC v.1.5.0.0 and Later Versions


In API RPC v.1.5.0.0 and later versions you should manage web user settings according to the following XML schema:

The password node is optional. It specifies a web user password. Data type: string. The password-type node is optional. It specifies if it is a plain or encrypted password (if encrypted, then the encryption method should be specified). Data type:string (length=4..64). The ftp-quota node is optional. It specifies the limit of space provided for a web user on the server. Data type: integer (-1 = unlimited). The services node is optional. It specifies web user services. Data type: ServicesType (webuser.xsd). The service node is required. It specifies a web user service. Data type: WebuserScriptType (webuser.xsd). The name node is required. It specifies the service name. Data type: sting. The value node is required. It specifies the service value. Data type: anySimple.

This packet sets PHP support for the web user with ID 14.
<packet version="1.5.0.0"> <webuser> <set> <filter> <id>14</id> </filter> <values> <services> <service> <name>php</name> <value>true</value> </service> </services> </values> </set></webuser></packet>

Supported Operations

1287

API RPC v.1.4.2.0 and Earlier Versions


This section describes web user settings. The settings can be set for a web user on creation, or they can be set for a web user later, or read from the database. The settings are defined by type WebUserSetParam (webuser.xsd). The graphical representation of the type is as follows:

The password node is optional. It specifies the web user password. Data type: string. The password-type node is optional. It specifies if it is a plain or encrypted password (if encrypted then the encryption method should be specified). Data type:string (length=4..64). The ftp-quota node is optional. It specifies the limit of space provided for a web user on the server. Data type: integer (-1 = unlimited). The asp node is optional. It specifies if the ASP support for Apache is provided. Data type: boolean. The asp-dot-net is optional. It specifies if the ASP.NET support is provided. This feature is supported only by Plesk for Windows. Data type: boolean. The ssi node is optional. It specifies if the SSI support is provided. Data type: boolean. The php node is optional. It specifies if the PHP support is provided. Data type: boolean. The cgi node is optional. It specifies if the CGI support is provided. Data type: boolean.

1288

Supported Operations

The mod-perl node is optional. It specifies if the mod_perl Apache module is supported. data type: boolean. The mod-python node is optional. It specifies if the mod_python Apache module is supported. Data type: boolean. The fastcgi node is optional. It specifies if the fastCGI extension is supported. Data type: boolean.

Remarks Once these preferences are set, all new web users (on the domain) will be created in accordance with them. All web user accounts existing on a certain domain will also stick to the preferences.

Preferences
The preferences common for the specified domain (for all web users of the domain) are defined by type WebUserPrefs (webuser.xsd). The graphical representation of the type is as follows:

The at-domains node is required. This node is used to enable or disable domains like username@mydomain.com, where username is the name of the specified web user, mydomain.com is your domain name. Data type: boolean.

Note: In Plesk 8.3 and later versions, you cannot change the at-domains node value. Although the node is required, the new value will be ignored by the server. This applies to all versions of API RPC protocol. The wuscripts node is required. It enables or disables web users to use web scripts. Data type: boolean.

Supported Operations

1289

Filtering Issues
Filtering is the way the request XML packet indicates the object (a web user or several) to which the operation is be applied. The request XML packet filters web user accounts using a special <filter> section. Parameters, nested in the filter node are called filtering rule. A filter contains as many different filtering rule types as the number of different parameters nested in the XML presentation of the filter node. A single operation can use only parameters of the same type in the filtering rule. There are two kinds of filters. The first filter matches all web users from the specified domain. This filter is used in getprefs and set-prefs operations. It is presented by type WebUserOwnFilter (webuser.xsd) and structured as follows:

The domain-id node is required. It specifies ID of the domain from which you want to select all web users. data type: integer. The domain-name node is required. It specifies the domain name from which you want to select all web users. Data type: string.

The second filter extends the first filter. In addition it matches web user accounts by either by id or login name. This filter is used in get, set and del operations. It is presented by type WebUserFilter (webuser.xsd) and structured as follows:

The id node is required. It specifies the ID of a web user. data type: integer. The login name is required. It specifies the login name of the web user. Data type: string. The domain-id node is required. It specifies the ID of the domain from which you want to select all web users. data type: integer.

1290

Supported Operations

The domain-name node is required. It specifies the domain name from which you want to select all web users. Data type: string.

Remarks A single filter can specify multiple web user accounts defined either by the ID or name in the first case, and either by the ID, name, domain-id or domain-name in the second. For example, a packet that retrieves information about web users with IDs 1, 2 and 3 looks as follows:
<packet version="1.4.2.0"> <webuser> <get> <filter> <id>1</id> <id>2</id> <id>3</id> </filter> </get> </webuser> </packet>

If an operation in a request packet(del, set, get-prefs, set-prefs) uses filters, the filter-id node is nested in a response packet. It returns the filtering rule parameter. If one of the following values was set as a filter rule parameter, it is returned in the filter-id node of the response packet. web user ID web user login name domain ID domain name

It is done to trace the request parameters in case of error. Data type: anySimple. Note: The <filter-id> node appears in API RPC 1.4.2.0. Earlier versions of the protocol do not support this node.

Supported Operations

1291

Creating Web Users


The add operation is used to create a web user on the certain domain. You can specify the web user settings on creation or set them later. By default, new web user account will be created in accordance with preferences set by Plesk Administrator. For information on web user settings and preferences, refer to the Web User Settings and Preferences (see page 1285) section.

In this section:
Request Packet Structure.................................................................................. 1291 Request Samples .............................................................................................. 1293 Response Packet Structure ............................................................................... 1294 Response Samples ........................................................................................... 1295

Request Packet Structure


A request XML packet adding a new web user includes the add operation node:
<packet version="1.4.2.0"> <webuser > <add> </add> </webuser> </packet>

1292

Supported Operations

The add node is presented by type WebUserAddInputType (webuser.xsd), and its graphical representation is as follows:

The domain-id node is required. It specifies the domain on which you want to create a web user. Data type: integer. The login node is required. It specifies the login name of the web user. Data type: string. The password node is optional. It specifies the web user password. Data type: string (length=4..64). The password-type node is optional. It specifies if it is a plain or encrypted password. Data type:string. Allowed values: plain | crypt. The ftp-quota node is optional. It specifies the limit of disk space (in bytes) provided for the web user on the server. Data type: integer (-1 = unlimited). The asp node is optional. It specifies if the ASP support for Apache is provided. Data type: boolean. The asp-dot-net is optional. It specifies if the ASP.NET support is provided. This feature is supported only by Plesk for Windows. Data type: boolean. The ssi node is optional. It specifies if the SSI support is provided. Data type: boolean The php node is optional. It specifies if the PHP support is provided. Data type: boolean.

Supported Operations

1293

The cgi node is optional. It specifies if the CGI support is provided. Data type: boolean. The mod-perl node is optional. It specifies if the mod_perl Apache module is supported. data type: boolean. The mod-python node is optional. It specifies if the mod_python Apache module is supported. Data type: boolean. The fastcgi node is optional. It specifies if the fastcgi extension is supported. Data type: boolean.

Note: The login name should begin with an alphabet character. It cannot contain white spaces. The password cannot contain quotation marks, white space, user's login name, and should be between 5 and 14 characters in length. Note: The password field can be left blank. If so, the web user is created but cannot login until the administrator creates the password for this user. Remarks You can add multiple users in a single packet. Use as many add operations as the number of web users to be added.

Request Samples
Adding a web user To add a web user, specify his login name and the ID of the domain where you want to add the new web user. The password is not specified, so the user cannot login until the password is set by the administrator.
<packet version="1.4.2.0"> <webuser> <add> <domain-id>12</domain-id> <login>myWebAccount</login> </add> </webuser> </packet>

Adding multiple web users To add more than one web user in a single packet, include two different add operations:
<packet version="1.4.2.0"> <webuser> <add> <domain-id>12</domain-id> <login>FirstWebUser</login> <password>1a3b5c</password> <ftp-quota>150</ftp-quota> <php>1</php> </add> <add> <domain-id>12</domain-id> <login>SecondWebUser</login>

1294

Supported Operations <fastcgi>0</fastcgi> </add> </webuser> </packet>

Response Packet Structure


The add node of the output XML packet is presented by type WebUserAddOutputType (webuser.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the add operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the add operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the add operation fails. Data type: string. The id node is optional. If the add operation succeeds it returns the ID of the added web user.

Supported Operations

1295

Response Samples
Adding a web user The request packet adding a new web user called myWebAccount looks as follows:
<packet version="1.4.2.0"> <webuser> <add> <domain-id>12</domain-id> <login>myWebAccount</login> </add> </webuser> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <add> <result> <status>ok</status> <id>321</id> </result> </add> </webuser> </packet>

If the operation fails a response can look as follows:


<packet version="1.4.2.0"> <webuser> <add> <result> <status>error</status> <errcode>1023</errcode> <errtext>Operation failed.</errtext> </result> </add> </webuser> </packet>

1296

Supported Operations

If the domain was not found on the server, the response can look as follows:
<packet version="1.4.2.0"> <webuser> <add> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> </result> </add> </webuser> </packet>

Deleting Web Users


Use the del operation to remove one or more web users from the domain.

In this section:
Request Packet Structure.................................................................................. 1296 Request Samples .............................................................................................. 1298 Response Packet Structure ............................................................................... 1299 Response Samples ........................................................................................... 1300

Request Packet Structure


A request XML packet removing a web user includes the del operation node:
<packet version="1.4.2.0"> <webuser > <del> </del> </webuser> </packet>

Supported Operations

1297

The del node is presented by type WebUserDelInputType (webuser.xsd), and its graphical representation is as follows:

The filter node is required. It specifies a filtering rule. For more information, refer to the Filtering Issues (see page 1289) section. Data type: WebUserFilter (webuser.xsd) The id node is required. It specifies the ID of a web user. data type: integer. The login name is required. It specifies the login name of the web user. Data type: string. The domain-id node is required. It specifies the ID of the domain from which you want to select all web users. data type: integer. The domain-name node is required. It specifies the domain name from which you want to select all web users. Data type: string.

Remarks You can remove multiple web users using different filtering rules in a single packet. Add as many del operations as the number of different filtering rules to be used.
<packet version="1.4.2.0"> <del> ... </del> ... <del> ... </del> </packet>

1298

Supported Operations

Request Samples
Deleting a web user To delete a web user, specify his login name or ID in the filter node. To delete several users in one del operation, use several ID's or login names in the same filter.
<packet version="1.4.2.0"> <webuser> <del> <filter> <login>WebUserOne</login> <login>WebUserTwo</login> </filter> </del> </webuser> </packet>

If you want to delete the web user specified by ID=156, the request packet looks as follows:
<packet version="1.4.2.0"> <webuser> <del> <filter> <id>156</id> </filter> </del> </webuser> </packet>

Deleting multiple web users You can delete all web users from the specified domain. The packet structure can look as follows:
<packet version="1.4.2.0"> <webuser> <del> <filter> <domain-name>example.com</domain-name> </filter> </del> </webuser> </packet>

Supported Operations

1299

If you want to delete all web users from the domain specified by ID 15, the request packet looks as follows:
<packet version="1.4.2.0"> <webuser> <del> <filter> <domain-id>156</domain-id> </filter> </del> </webuser> </packet>

Response Packet Structure


The del node of the output XML packet is presented by type WebUserDelOutputType (webuser.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the del operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the del operation fails. Data type: unsignedInt. The errcode node is optional. It returns the error code if the del operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the del operation fails. Data type: string.

1300

Supported Operations

The filter-id node is required. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 1289) section. Data type:anySimpleType. The id node is optional. If the del operation succeeds it holds the ID of the deleted web user. Data type: integer.

Response Samples
Deleting a web user Send the following request to delete the web user identified by login name AbCdEf.
<packet version="1.4.2.0"> <webuser> <del> <filter> <login>AbCdEf</login> </filter> </del> </webuser> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <webuser> <del> <result> <status>ok</status> <filter-id>AbCdEf</filter-id> <id>253</id> </result> </del> </webuser> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <del> <result> <status>error</status> <errcode>1013</errcode> <errtext>Web user does not exist.</errtext> <filter-id>AbCdEf</filter-id> </result> </del> </webuser> </packet>

Supported Operations

1301

Deleting multiple web users The following request removes all web users from example.com and example2.com domains:
<packet version="1.4.2.0"> <webuser> <del> <filter> <domain-name>example.com</domain-name> <domain-name>example2.com</domain-name> </filter> </del> </webuser> </packet>

Two web users on example.com were deleted. example2.com was not found on the server. The response looks as follows:
<packet version="1.4.2.0"> <webuser> <del> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>156</id> </result> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>157</id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain name does not exist</errtext> <filter-id>example2.com</filter-id> </result> </del> </webuser> </packet>

1302

Supported Operations

Updating Web User Settings


Use the set operation to change settings for existing web users on the domain.

In this section:
Request Packet Structure.................................................................................. 1302 Request Samples .............................................................................................. 1303 Response Packet Structure ............................................................................... 1304 Response Samples ........................................................................................... 1306

Request Packet Structure


A request XML packet updating settings of web users includes the set operation node:
<packet version="1.4.2.0"> <webuser > <set> </set> </webuser> </packet>

The set node is presented by type WebUserSetInputType (webuser.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 1289) section. Data type: WebUserFilter (webuser.xsd). The values node is required. It specifies settings that are updated for web users. For more information, refer to the Web User Settings and Preferences (see page 1285) section. Data type: WebUserSetParam (webuser.xsd).

Supported Operations

1303

Remarks You can change settings of multiple web users using different filtering rules in a single packet. Add as many set operations as the number of different filtering rules to be used.
<packet version="1.4.2.0"> <set> ... </set> ... <set> ... </set> </packet>

Request Samples
Updating settings of a single web user This packet disables PHP and CGI scripts execution for users of the domain specified by ID 13.
<packet version="1.4.2.0"> <webuser> <set> <filter> <domain-id>13</domain-id> </filter> <values> <php>0</php> <cgi>0</cgi> </values> </set> </webuser> </packet>

1304

Supported Operations

Updating settings of multiple web users This packet sets the password for the web user with ID 14 and for the web user called MyUser.
<packet version="1.4.2.0"> <webuser> <set> <filter> <id>13</id> </filter> <values> <password>1a3b5</password> </values> </set> <set> <filter> <login>MyUser</login> </filter> <values> <password>2c4d6e</password> </values> </set> </webuser> </packet>

Supported Operations

1305

Response Packet Structure


The set node of the output XML packet is presented by type WebUserSetOutputType (webuser.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the set operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the set operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the set operation fails. Data type: string. The filter-id node is required. It returns a filtering rule parameter. For more information, refer to the Filtering Issues (see page 1289) section. Data type: anySimpleType. The id node is optional. If the set operation succeeds it holds the ID of the updated web user. Data type: integer.

1306

Supported Operations

Response Samples
Updating settings of a single web user An Agent sends the following request to disable CGI and fastCGI support for the web user identified by login name AbCdEf.
<packet version="1.4.2.0"> <webuser> <set> <filter> <login>AbCdEf</login> </filter> <values> <cgi>0</cgi> <fastcgi>0</fastcgi> </values> </set> </webuser> </packet>

The positive response from the server looks as follows:


<packet version="1.4.2.0"> <webuser> <set> <result> <status>ok</status> <filter-id>AbCdEf</filter-id> <id>14</id> </result> </set> </webuser> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <set> <result> <status>error</status> <errcode>1013</errcode> <errtext>Web user does not exist</errtext> <filter-id>AbCdEf</filter-id> </result> </set> </webuser> </packet>

Supported Operations

1307

Updating settings of multiple web users The request packet is as follows:


<packet version="1.4.2.0"> <webuser> <set> <filter> <domain-id>13</domain-id> <domain-id>14</domain-id> </filter> <values> <mod-python>0</mod-python> </values> </set> </webuser> </packet>

For example, three users updated on the domain with ID 14. The domain with ID 13 was not found on the server. The server response looks as follows:
<packet version="1.4.2.0"> <webuser> <set> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>13</filter-id> </result> <result> <status>ok</status> <filter-id>14</filter-id> <id>168</id> </result> <result> <status>ok</status> <filter-id>14</filter-id> <id>158</id> </result> <result> <status>ok</status> <filter-id>14</filter-id> <id>116</id> </result> </set> </webuser> </packet>

1308

Supported Operations

Retrieving Web Users Settings


Use the get operation to retrieve settings of web users on a specified domain. A web user settings have less priority than web user preferences. If you cannot update web user settings - check web users preferences of the domain. For more information on the preferences, refer to the Retrieving Web Users Preferences (see page 1314) section.

In this section:
Request Packet Structure.................................................................................. 1308 Request Samples .............................................................................................. 1309 Response Packet Structure ............................................................................... 1310 Response Samples ........................................................................................... 1311

Request Packet Structure


A request XML packet retrieving settings of web users includes the get operation node:
<packet version="1.4.2.0"> <webuser > <get> </get> </webuser> </packet>

The get node is presented by type WebUserSetInputType (webuser.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 1289) section. Data type: WebUserFilter (webuser.xsd).

Supported Operations

1309

Remarks You can retrieve settings of multiple web users using different filtering rules in a single packet. Add as many get operations as the number of different filtering rules to be used.
<packet version="1.4.2.0"> <get> ... </get> ... <get> ... </get> </packet>

Request Samples
Retrieving a web user settings This packet retrieves settings of all web users of the domain with ID 5.
<packet version="1.4.2.0"> <webuser> <get> <filter> <domain-id>5</domain-id> </filter> </get> </webuser> </packet>

Retrieving settings of multiple web users This packet retrieves settings of two web users. The first is identified by login name MyWebAcc1, the second is identified by ID 54.
<packet version="1.4.2.0"> <webuser> <get> <filter> <login>MyWebAcc1</login> </filter> </get> <get> <filter> <id>54</id> </filter> </get> </webuser> </packet>

1310

Supported Operations

Response Packet Structure


The get node of the output XML packet is presented by type WebUserGetOutputType (webuser.xsd) and structured as follows:

Supported Operations

1311

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the get operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get operation fails. Data type: string. The filter-id node is required. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 1289) section. Data type:anySimpleType. The id node is optional. If the get operation succeeds it holds the id of the web user. Data type: integer. The following nodes are required only if the get operation succeeds: The login node is optional. Returns the login name of a web user. Data type: string. The ftp-quota node is optional. It specifies the limit of disk space (in bytes) provided for a web user on the server. Data type: integer. The asp node is optional. It specifies if the ASP support for Apache is provided. Data type: boolean. The asp-dot-net is optional. It specifies if the ASP.NET support is provided. This feature is supported only by Plesk for Windows. Data type: boolean. The ssi node is optional. It specifies if the SSI support is provided. Data type: boolean. The php node is optional. It specifies if the PHP support is provided. Data type: boolean. The cgi node is optional. It specifies if the CGI support is provided. Data type: boolean. The mod-perl node is optional. It specifies if the mod_perl Apache module is supported. data type: boolean. The mod-python node is optional. It specifies if the mod_python Apache module is supported. Data type: boolean. The fastcgi node is optional. It specifies if the fastcgi extension is supported. Data type: boolean.

Note: If a value for a node is "false", it is not nested in the packet.

1312

Supported Operations

Response Samples
Retrieving a web user settings The following request retrieves settings of the web user with login name abcdef.
<packet version="1.4.2.0"> <webuser> <get> <filter> <login>abcdef</login> </filter> </get> </webuser> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <get> <result> <status>ok</status> <filter-id>abcdef</filter-id> <id>17</id> <login>abcdef</login> <ftp-quota>-1</ftp-quota> </result> </get> </webuser>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Web user does not exist</errtext> <filter-id>abcdef</filter-id> </result> </get> </webuser>

Supported Operations

1313

Retrieving multiple web users settings The following request retrieves settings of all web users from example.com, and example2.com domains.
<packet version="1.4.2.0"> <webuser> <get> <filter> <domain-name>example.com</domain-name> <domain-name>example2.com</domain-name> </filter> </get> </webuser> </packet>

Two web users on example.com and one on example2.com match the filtering rule. A positive response from the server can look as follows:
<packet version="1.4.2.0"> <webuser> <get> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>17</id> <login>FirstUser</login> <ftp-quota>-1</ftp-quota> <php>true</php> <cgi>true</cgi> </result> <result> <status>ok</status> <filter-id>example.com</filter-id> <id>18</id> <login>SecondUser</login> <ftp-quota>100</ftp-quota> <php>true</php> </result> <result> <status>ok</status> <filter-id>example2.com</filter-id> <id>11</id> <login>FirstUser</login> <ftp-quota>100</ftp-quota> <php>true</php> </result> </get> </webuser> </packet>

1314

Supported Operations

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <get> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>example.com</filter-id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>example2.com</filter-id> </result> </get> </webuser> </packet>

Retrieving Web Users Preferences


Use the get operation to retrieve preferences common for all users of a certain domain. These settings automatically will be applied to a new user added to the domain. Web users preferences are of more priority than web user settings. For more information on the settings, refer to the Retrieving Web Users Settings (see page 1308) and Web User Settings and Preferences (see page 1285) sections.

In this section:
Request Packet Structure.................................................................................. 1315 Request Samples .............................................................................................. 1316 Response Packet Structure ............................................................................... 1316 Response Samples ........................................................................................... 1318

Supported Operations

1315

Request Packet Structure


A request XML packet retrieving preferences of web users includes the get-prefs operation node:
<packet version="1.4.2.0"> <webuser > <get-prefs> </get-prefs> </webuser> </packet>

The get-prefs node is presented by type WebUserGetPrefInputType (webuser.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 1289) section. Data type: WebUserOwnFilter (webuser.xsd)

Remarks You can retrieve preferences of web users using different filtering rules in a single packet. Add as many get-prefs operations as the number of different filtering rules to be used.
<packet version="1.4.2.0"> <get-prefs> ... </get-prefs> ... <get-prefs> ... </get-prefs> </packet>

1316

Supported Operations

Request Samples
Retrieving a web user preferences This packet retrieves preferences of all web users of the domain with ID 5.
<packet version="1.4.2.0"> <webuser> <get-prefs> <filter> <domain-id>5</domain-id> </filter> </get-prefs> </webuser> </packet>

Retrieving preferences of multiple web users This packet retrieves preferences of all web users of domain example.com.
<packet version="1.4.2.0"> <webuser> <get-prefs> <filter> <domain-name>example.com</domain-name> </filter> </get-prefs> </webuser> </packet>

Supported Operations

1317

Response Packet Structure


The get-prefs node of the output XML packet is presented by type WebUserGetPrefOutputType (webuser.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the get-prefs operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the get-prefs operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get-prefs operation fails. Data type: string. The filter-id node is required. It returns the filtering rule parameter. For more information, refer to the Filtering Issues (see page 1289) section. Data type: anySimple. The id node is optional. If the set operation succeeds it holds the ID of the updated web user. Data type: integer. The at-domains node is optional. It is required if the get-prefs operation succeeds. It indicates that the web user can use domains like username@mydomain.com, where username is the name of the specified web user, mydomain.com is your domain name. Data type: boolean. The wuscripts node is optional. It is required if the get-prefs operation succeeds. It indicates if web users are able to use web scripts. Data type: boolean.

1318

Supported Operations

Response Samples
Retrieving preferences a web user This packet retrieves preferences of all web users of the domain with ID 5. The packet can look as follows:
<packet version="1.4.2.0"> <webuser> <get-prefs> <filter> <domain-id>5</domain-id> </filter> </get-prefs> </webuser>

A positive response packet can look as follows:


<packet version="1.4.2.0"> <webuser> <get-prefs> <result> <status>ok</status> <filter-id>5</filter-id> <id>5</id> <at-domains>false</at-domains> <wuscripts>true</wuscripts> </result> </get-prefs> </webuser>

Retrieving preferences of multiple domains. This packet retrieves preferences of all web users of domains example.com and example2.com. The request packet looks as follows:
<packet version="1.4.2.0"> <webuser> <get-prefs> <filter> <domain-name>example.com</domain-name> <domain-name>example2.com</domain-name> </filter> </get-prefs> </webuser>

Supported Operations

1319

A response packet can look as follows:


<packet version="1.4.2.0"> <webuser> <get-prefs> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>example.com</filter-id> </result> <result> <status>ok</status> <filter-id>example2.com</filter-id> <id>6</id> <at-domains>true</at-domains> <wuscripts>true</wuscripts> </result> </get-prefs> </webuser>

Updating Web Users Preferences


Use the set-prefs operation to change preferences common for all users of the certain domain. These settings automatically will be set for a new user added to the domain. Web users preferences are of more priority than web users settings. For more information on the settings, refer to the Retrieving Web Users Settings (see page 1308), and Web User Settings/Preferences (see page 1285) sections.

In this section:
Request Packet Structure.................................................................................. 1320 Request Samples .............................................................................................. 1321 Response Packet Structure ............................................................................... 1322 Response Samples ........................................................................................... 1323

1320

Supported Operations

Request Packet Structure


A request XML packet updating preferences of web users includes the set-prefs operation node:
<packet version="1.4.2.0"> <webuser > <set-prefs> </set-prefs> </webuser> </packet>

The set-prefs node is presented by type WebUserSetPrefInputType (webuser.xsd), and its graphical representation is as follows:

The filter node is required. It specifies the filtering rule. For more information, refer to the Filtering Issues (see page 1289) section. Data type: WebUserOwnFilter (webuser.xsd) The values node is required. It specifies preferences of a domain. For more information, refer to the Preferences (on page 1288) section. Data type: WebUserPrefs (webuser.xsd)

Remarks You can update preferences of web users using different filtering rules in a single packet. Add as many set-prefs operations as the number of different filtering rules to be used.
<packet version="1.4.2.0"> <set-prefs> ... </set-prefs> ... <set-prefs> ... </set-prefs> </packet>

Supported Operations

1321

Request Samples
Updating preferences of a single domain. This packet disables scripts execution for all web users of the domain with ID 4.
<packet version="1.4.2.0"> <webuser> <set-prefs> <filter> <domain-id>4</domain-id> </filter> <values> <at-domains>1</at-domains> <wuscripts>0</wuscripts> </values> </set-prefs> </webuser> </packet>

Updating preferences of multiple domains. This packet disables both scripts execution and domains like username@<domain> for all web users of example.com and example2.com domains.
<packet version="1.4.2.0"> <webuser> <set-prefs> <filter> <domain-id>example.com</domain-id> <domain-id>example2.com</domain-id> </filter> <values> <at-domains>0</at-domains> <wuscripts>0</wuscripts> </values> </set-prefs> </webuser> </packet>

1322

Supported Operations

Response Packet Structure


The set-prefs node of the output XML packet is presented by type WebUserSetPrefOutputType (webuser.xsd) and structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultFilterType (common.xsd). The status node is required. It specifies the execution status of the set-prefs operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code if the set-prefs operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the set-prefs operation fails. Data type: string. The filter-id node is required. It returns filtering rule parameter. For more information, refer to the Filtering Issues (see page 1289) section. Data type:anySimpleType. The id node is optional. If the set-prefs operation succeeds it holds the id of the updated web user. Data type: integer.

Supported Operations

1323

Response Samples
Updating preferences of a single domain. The request packet disables scripts execution for all web users of the domain with ID 4.
<packet version="1.4.2.0"> <webuser> <set-prefs> <filter> <domain-id>4</domain-id> </filter> <values> <at-domains>1</at-domains> <wuscripts>0</wuscripts> </values> </set-prefs> </webuser> </packet>

A positive response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <set-prefs> <result> <status>ok</status> <filter-id>4</filter-id> <id>4</id> </result> </set-prefs> </webuser> </packet>

A negative response from the server can look as follows:


<packet version="1.4.2.0"> <webuser> <set-prefs> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>4</filter-id> </result> </set-prefs> </webuser> </packet>

Updating preferences of multiple domains. This request packet disables scripts execution, and domains like username@<domain> for all web users of the example.com and example2.com domains.

1324

Supported Operations <packet version="1.4.2.0"> <webuser> <set-prefs> <filter> <domain-id>example.com</domain-id> <domain-id>example2.com</domain-id> </filter> <values> <at-domains>0</at-domains> <wuscripts>0</wuscripts> </values> </set-prefs> </webuser> </packet>

A response from the server can look as follows (example2.com wasn't found on the server):
<packet version="1.4.2.0"> <webuser> <set-prefs> <result> <status>ok</status> <filter-id>Domain1.com</filter-id> <id>4</id> </result> <result> <status>error</status> <errcode>1015</errcode> <errtext>Domain does not exist</errtext> <filter-id>Domain2.com</filter-id> </result> </set-prefs> </webuser> </packet>

Supported Operations

1325

Migrating Domain And Client Accounts


Operator: <migration> XML Schema: migration_input.xsd, migration_output.xsd, plesk_migration.xsd Plesk version: Plesk 8.0 for Unix and later | Plesk 8.3 for Windows and later API RPC version: 1.4.0.0 and higher Plesk user: Plesk Administrator Description Plesk for Unix provides Plesk Migration Manager tool capable of transferring client and domain accounts (including related resources, namely, databases used on domains) from one Plesk server (source server) to another (destination server). Migration is a process of such client/ domain transfer. Plesk for Windows Migration Manager allows migrating hosting data not only from Plesk for Unix and Plesk for Windows servers, but also from other hosting control panels. For information on Plesk for Windows migration specifics and PMM functionality, refer to the Plesk for Windows Migration Manager Administrator's Guide which is available at the Parallels Plesk Documentation Page. The current document covers only Plesk application programming interface to the Plesk Migration Manager. Migrations are always processed by destination Plesk servers, namely, by Plesk servers to which client or domain accounts are transferred. Therefore, all the migration request packets are sent to the destination Plesk server. Important: It is important for performing any operation with the migration operator that Plesk Migration Manager is installed on the destination Plesk server.

1326

Supported Operations

Two types of migration are supported by Plesk API RPC, they are Domain Migration and Client Migration. The difference is as follows:
Migration Type Migration Item Data Migrated Domain Migration Domain Account (see page 1341) Client Migration (see page 1337) Client Account All domain settings always migrated (including general settings, limits, domain administrator's settings, hosting parameters, mail settings, etc.) and content Domain IP address Domain database(s) content Client account general settings, client's limits and permissions Client's IP pool Client's domains always migrated always migrated always migrated

always migrated optional

Supported operations:

START (see page 1335) starts migration of particular client or domain accounts from specified source Plesk server to specified target Plesk server. FINISH (see page 1356) stops the migration defined by ID. GET_FS (see page 1333) retrieves information on file system on the specified host (may be important for defining source and destination host directories in request packet starting (see page 1335) migration). GET_STATUS (see page 1350) retrieves the current status of the migration defined by ID. CHECK (see page 1331) checks whether Plesk Migration Manager is installed on Plesk server.

Supported Operations

1327

In this section:
IP Addresses Mapping ...................................................................................... 1327 Databases Mapping .......................................................................................... 1329 Checking Plesk Migration Manager Installation ................................................. 1331 Retrieving File System Information .................................................................... 1333 Starting Migration .............................................................................................. 1335 Retrieving Migration Status ............................................................................... 1350 Stopping Migration ............................................................................................ 1356

IP Addresses Mapping
IP mapping is an important component of migrating domain and client accounts: It specifies which IP addresses existing on destination Plesk server must be assigned to migrated domain or client accounts when the migration is completed. Mapping IP addresses is required in all cases when an object to be migrated (client or domain) has IP addresses assigned to it on source host. In case of migrating client, these are IP addresses in the client's IP pool. In case of migrating domain with physical hosting, it is IP address on which the domain is hosted. IP mapping is senseless when a client has empty IP pool or a domain with hosting type standard forwarding or frame forwarding is migrated. If no IP mapping rules are defined, objects being migrated are transferred to the destination host with IP addresses values that were assigned to them on the source host. IP mapping is defined by the ip node used in the start request packet. The node is defined by complex type MappedIp. (plesk_migration.xsd), which is structured as follows:

1328

Supported Operations

The old node is required. It specifies properties of a source host IP address assigned to an object to be migrated. Data type: Ip (plesk_migration.xsd). The node new is required. It specifies properties of a destination host IP address that should be assigned to an object after it is migrated. Data type: Ip (plesk_migration.xsd). The ip-type node is required. It specifies whether the IP address is of exclusive or shared type. Data type: ip_address (common.xsd). Allowed values: shared | exclusive. The ip-address node is required. It specifies the IP address. Data type: ip_address (common.xsd).

Remarks 1. Node ip-address nested in the new node should contain only IP address which already exists on destination Plesk server, as no new IP addresses are created with the migration operator. 2. For information on retrieving client IP pool, refer to the Getting Information About Client Accounts (see page 87) section. 3. For information on retrieving IP address on which a domain is hosted, refer to the Getting Information About Domain Accounts (see page 429) section.

Sample The following packet starts migrating domain example3.com from host plesk.example.com to host plesk.example2.com (to which the request packet is sent). The packet maps source domain IP address 192.0.2.85 (exclusive) to destination IP 192.0.2.55 (exclusive), on which the domain will be hosted when the migration is completed.
<packet version=1.4.2.0> <migration> <start> <host>plesk.example.com</host> <login>admin</login> <password>aBcDeF</password> <source-host-directory>/tmp_src</source-host-directory> <destination-host-directory>/tmp_dst</destination-host-directory> <selected-objects> <migrate-domains> <target-client>John Doe</target-client> <domain> <name>example3.com</name> <ip> <old> <ip-type>exclusive</ip-type> <ip-address>192.0.2.85</ip-address> </old> <new> <ip-type>exclusive</ip-type> <ip-address>192.0.2.55</ip-address>

Supported Operations </new> </ip> </domain> </migrate-domains> </selected-objects> </start> </migration> </packet>

1329

Databases Mapping
Databases mapping is important in case of migrating domain with databases created and used on it: It defines on what database server registered in destination Plesk the domain databases should be hosted after migration. If no database mapping rules are defined, databases registered on the domain being migrated are created on the default database server of the corresponding type. Database mapping is defined by the db-server node used in the start request packet. The node is defined by type MappedDbServer (plesk_migration.xsd). The db-server node is structured as follows:

The old node is required. It wraps properties of source database server where databases of the domain to be migrated exist. Data type: DbServer (plesk_migration.xsd). The new node is required. It wraps properties of destination database server where databases of the domain to be migrated will be transferred to. Data type: DbServer (plesk_migration.xsd). The host node is required. It specifies the name or IP address of the source/ destination database server. Data type: string. The port node is required. It specifies the number of port on which the database server is listening. Data type: string. Allowed values:

1330

Supported Operations

The type node is required. It specifies the database server type. MySQL and PostgreSQL types are available. Data type: string. Allowed values: mysql | postgresql.

Note: To retrieve information on a database server registered in Plesk, use the db_server:GET (on page 189) operation. To retrieve information on default database server of a particular type, use the db_server:GET_DEFAULT (on page 184) operation.

The following packet starts migrating domain doe.com from Plesk for Unix host 'plesk1' to Plesk for Unix host 'plesk2' (to which the request packet is sent). The packet maps source MySQL database server 'msql3' to the destination MySQL server hosted on the Plesk server.
<packet version=1.4.2.0> <migration> <start> <host>plesk1</host> <login>admin</login> <password>setup</password> <source-host-directory>/tmp_src</source-host-directory> <destination-host-directory>/tmp_dst</destination-host-directory> <selected-objects> <migrate-domains> <target-client>John Doe</target-client> <domain> <name>doe.com</name> <db-server> <old> <host>msql3</host> <port>3306</port> <type>mysql</type> </old> <new> <host>localhost</host> <port>3306</port> <type>mysql</type> </new> </db-server> </domain> </migrate-domains> </selected-objects> </start> </migration> </packet>

Supported Operations

1331

Checking Plesk Migration Manager Installation


Before you start migrating client or domain accounts, it is recommended that you check if Plesk Migration Manager is installed on Plesk server taking into account the following: in Plesk for Unix, performing migration is possible if Plesk Migration Manager is installed on both source and destination Plesk servers in Plesk for Windows, performing migration is possible if PMM is installed on destination Plesk server and Plesk Migration Agent is installed on a source server (the last cannot be checked via API RPC)

To check if Plesk Migration manager is installed on a Plesk server, send the request packet containing the check operational node:
<packet version="1.5.2.0"> <migration> <check/> </migration> </packet>

Response Packet Structure The check node in the response packet received from server is structured as follows:

The result node is required. It wraps the result of the check operation. Data type: resultType. The status node is required. It returns the execution status of the check operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the check operation fails. Data type: unsignedInt The errtext node is optional. It returns the error message if the check operation fails. Data type: string.

1332

Supported Operations

Response Samples If Plesk Migration Manager is installed on a server to which a request packet was sent, the response from the server looks as follows:
<packet version="1.5.2.0"> <migration> <check> <result> <status>ok</status> </result> </check> </migration> </packet>

The following response is received if the request packet was sent to a server on which Plesk Migration Manager is not installed.
<packet version="1.5.2.0"> <migration> <check> <result> <status>error</status> <errcode>1026</errcode> <errtext>Plesk Migration Manager is not installed</errtext> </result> </check> </migration> </packet>

Supported Operations

1333

Retrieving File System Information


This operation makes sense only if performing migration in Plesk for Unix. Before starting a migration, you may want to get information on the source or destination file system, in order to specify the most suitable directory for storing migration dump. To get a server file system information, send request packet containing the get_fs operation node structured as follows:
<packet version="1.4.2.0"> <migration> <get_fs/> </migration> </packet>

Response Packet Structure The get_fs node in the response packet received from server is structured as follows:

1334

Supported Operations

The result node is required. It wraps the result of the get_fs operation. Data type: MigrationOutputGetFsResultType. The status node is required. It returns the execution status of the get_fs operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the get_fs operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the get_fs operation fails. Data type: string. The fs node is required. It holds the collection of data describing a file system on the host. The number of the fs nodes in the response packet is equal to number of partitions on the host (ignoring swap partition). Data type: FS. The mountpoint node is required. It returns the partition mount point. Data type: string. The device node is required. It returns the device on which the file system exists. Data type: string. The mode node is required. It returns mount options of the file system. Data type: FsReadWriteStatus. Allowed values: rw | r. The size node is required. It returns total size of the file system (in bytes). Data type: string. The free node is required. It returns the amount of free space on the file system (in bytes). Data type: string. The type node is required. It returns the file system type. Data type: string.

Response Samples A positive response received from server can look as follows:
<packet version="1.4.2.0"> <migration> <get_fs> <result> <status>ok</status> <fs> <mountpoint>/</mountpoint> <device>/dev/sda1</device> <mode>rw</mode> <size>4015644672</size> <free>1549070336</free> <type>ext3</type> </fs> </result> </get_fs> </migration> </packet>

Supported Operations

1335

A negative response received from Plesk for Windows server looks as follows:
<packet version="1.5.2.0"> <migration> <get_fs> <result> <status>error</status> <errcode>1017</errcode> <errtext>operator get_fs is </result> </get_fs> </migration> </packet>

not supported</errtext>

Starting Migration
To start a migration, send a request XML packet containing the start operational node to the destination Plesk server. You can start migration of either domain account(s) or client account(s) with one start operation. A request XML packet starting a migration includes the start operation node:
<packet version="1.4.2.0"> <migration> <start> </start> </migration> </packet>

The start node is presented by type MigrationArguments (plesk_migration.xsd), and its graphical representation is as follows:

1336

Supported Operations

The host node is required. It specifies name or IP address of the source server. Data type: string. The login node is required. It specifies the control panel Administrator's login name on the source server. Data type: string. The password node is required. It specifies the control panel Administrator's password on the source server. Data type: string. The source-host-directory node is required. It specifies path to the directory on the source server file system, where the dump of objects being migrated will be created. Data type: string. Supported in Plesk for Unix only, must be used with empty value in Plesk for Windows. The destination-host-directory node is required. It specifies path to the directory on the destination server file system, where the dump of objects being migrated will be stored before deploying them to Plesk. Data type: string. Supported in Plesk for Unix only, must be used with empty value in Plesk for Windows. The system-type node is required in Plesk for Windows. It specifies the type of operating system running on source server. Data type: string. Allowed values: unix | windows. The node is available since protocol v.1.5.2.0. The selected-objects node is required. It defines whether client or domain accounts will be transferred with the migration. Data type: SelectedObjects. The migrate-clients node is optional. It defines that the client accounts migration will be started, and wraps the collection of data defining what client accounts should be migrated and the migration options. For the detailed information on this node structure, refer to the Starting Client Migration (see page 1337) section. Data type: SelectedClients. The migrate-domains node is optional. It defines that the domain accounts migration will be started, and wraps the collection of data defining what domain accounts should be migrated and the migration options. For the detailed information on this node structure, refer to the Starting Domain Migration (see page 1341) section. Data type: SelectedDomains.

Note: With one START operation, you can migrate either client or domain accounts from one Plesk server . However, you can always migrate different client and domain accounts located on the same or different Plesk servers with one request packet, just use as many start nodes as you want.

In this section:
Starting Client Migration .................................................................................... 1337 Starting Domain Migration ................................................................................. 1341 Response Packet Structure ............................................................................... 1346 Response Samples ........................................................................................... 1347

Supported Operations

1337

Starting Client Migration


To transfer client account(s) to Plesk, nest the migrate-client node into the selectedobjects node. The node is defined by complex type SelectedClients (plesk_migration.xsd) and structured as follows:

The client node is required. It wraps the settings of a client account migration. Data type: MappedClient (plesk_migration.xsd). The name node is required. It specifies the login name of a client to be migrated. Data type: string. The ip node is optional. It defines mapping rules for IP addresses in the client's IP pool. For information on this node structure, refer to the IP Addresses Mapping (see page 1327) section. Data type: MappedIp (plesk_migration.xsd). The domain node is optional. It holds the collection of data defining migration settings for the client's domain that should be migrated together with the client account. Data type: MappedDomain (plesk_migration.xsd). The name node is required. It defines the name of the client's domain (in unicode) that should be migrated. Data type: string. The ip node is optional. It defines mapping rules for the IP address on which the domain is hosted. For information on this node structure, refer to the IP Addresses Mapping (see page 1327) section. Data type: MappedIp (plesk_migration.xsd). The db-server node is optional. It defines mapping rules for databases used on the domain. For information on this node structure, refer to the Databases Mapping (see page 1329) section. Data type: MappedDbServer (plesk_migration.xsd).

Remarks With one start operation, you can start migrating multiple clients, just use as many client nodes as the required number of client accounts.

1338

Supported Operations

Request Samples
1. Starting migrations in Plesk for Windows 1.1. Migrating a single client account This packet starts migration (with only the required options specified) of the client account with login name "john_doe" from remote Plesk for Unix server. After the migration is completed, there will be the client account in destination Plesk database, with empty IP pool and no domains registered for this client.
<packet version="1.5.2.0"> <migration> <start> <host>192.0.2.36</host> <login>admin</login> <password>Lkejd8UU</password> <source-host-directory/> <destination-host-directory/> <system-type>unix</system-type> <selected-objects> <migrate-clients> <client> <name>john_doe</name> </client> </migrate-clients> </selected-objects> </start> </migration> </packet>

1.2. Migrating multiple client accounts This packet starts migration of two client accounts with login names "terry_sepir" and "terry_worf" from server running Windows, with the required options only. After the migration is completed, there will be these client accounts in destination Plesk, with empty IP pool and no domains registered for these clients.
<packet version="1.5.2.0"> <migration> <start> <host>192.0.2.50</host> <login>admin</login> <password>Lkejd8UU</password> <source-host-directory/> <destination-host-directory/> <system-type>windows</system-type> <selected-objects> <migrate-clients> <client> <name>terry_sepir</name> </client> <client> <name>terry_worf</name> </client> </migrate-clients></selected-objects> </start></migration></packet>

Supported Operations

1339

2. Starting migrations in Plesk for Unix 2.1. Migrating a single client account This packet starts migration (with the required options) of the client account with login name "john_doe". After the migration is completed, there will be the client account in destination Plesk database, with empty IP pool and no domains registered for this client.
<packet version="1.4.2.0"> <migration> <start> <host>212.58.49.36</host> <login>admin</login> <password>Lkejd8UU</password> <source-host-directory>/tmp_src</source-host-directory> <destination-host-directory>/tmp_dst</destination-host-directory> <selected-objects> <migrate-clients> <client> <name>john_doe</name> </client> </migrate-clients> </selected-objects> </start> </migration> </packet>

This packet starts migration of client account with login name "jimmy_jones" and domain example.com belonging to this account. The packet also performs IP mapping for the client's IP pool and the IP on which the domain is hosted.
<packet version="1.4.2.0"> <migration> <start> <host>212.58.49.37</host> <login>admin</login> <password>LKL00jdhTT</password> <source-host-directory>/tmp</source-host-directory> <destination-host-directory>/tmp</destination-host-directory> <selected-objects> <migrate-clients> <client> <name>jimmy_jones</name> <ip> <old> <ip-type>shared</ip-type> <ip-address>192.0.2.50</ip-address> </old> <new> <ip-type>shared</ip-type> <ip-address>192.0.2.60</ip-address> </new> </ip> <domain> <name>jimmyjones.com</name> <ip> <old>

1340

Supported Operations <ip-type>shared</ip-type> <ip-address>192.0.2.50</ip-address> </old> <new> <ip-type>shared</ip-type> <ip-address>192.0.2.60</ip-address> </new> </ip> </domain> </client> </migrate-clients> </selected-objects> </start> </migration> </packet>

2.2. Migrating multiple client accounts This packet starts migration of two client accounts with login names "terry_sepir" and "terry_worf", with the required options only. After the migration is completed, there will be these client accounts in destination Plesk database, with empty IP pool and no domains registered for these clients.
<packet version="1.4.2.0"> <migration> <start> <host>212.58.49.50</host> <login>admin</login> <password>Lkejd8UU</password> <source-host-directory>/tmp/migr</source-host-directory> <destination-host-directory>/tmp/migr</destination-host-directory> <selected-objects> <migrate-clients> <client> <name>terry_sepir</name> </client> <client> <name>terry_worf</name> </client> </migrate-clients> </selected-objects> </start> </migration> </packet>

Supported Operations

1341

Starting Domain Migration


To transfer a domain account to Plesk, nest the migrate-domain node into the selectedobjects node. The node is defined by complex type SelectedDomains (plesk_migration.xsd) and structured as follows:

The target-client node is required. It defines the login name of a client account to which the domains will belong when the migration is completed. Data type: string. The domain node is required. It holds the collection of data defining settings for the migration of a domain account. Data type: MappedDomain (plesk_migration.xsd). The name node is required. It defines the name of the domain (in unicode) that should be migrated. Data type: string. The ip node is optional. It defines mapping rules for the IP address on which the domain is hosted. For information on this node structure, refer to the IP Addresses Mapping (see page 1327) section. Data type: MappedIp (plesk_migration.xsd). The db-server node is optional. It defines mapping rules for databases used on the domain. For information on this node structure, refer to the Databases Mapping (see page 1329) section. Data type: MappedDbServer (plesk_migration.xsd).

Remarks With one start operation, you can migrate multiple domains to multiple client accounts on the destination Plesk server, just use as many migrate-domains nodes as the required number of clients. You can also migrate multiple domains to a client as well. In this case, use multiple domain nodes.

1342

Supported Operations

Request Samples
1. Starting migrations in Plesk for Windows 1. Migrating a single domain account This packet starts migration of domain called samples.org from remote Plesk for Windows server with only the required options specified. When the migration is completed, the domain will belong to client with login name "mary_jane".
<packet version="1.5.2.0"> <migration> <start> <host>192.0.2.220</host> <login>admin</login> <password>jkSGtvbg55</password> <source-host-directory/> <destination-host-directory/> <system-type>windows</system-type> <selected-objects> <migrate-domains> <target-client>mary_jane</target-client> <domain> <name>samples.org</name> </domain> </migrate-domains> </selected-objects> </start> </migration> </packet>

1.2. Migrating multiple domains to a single client account This packet starts migration of domains called rustyart.org and grungyart.org from remote server running Linux. When the migration is completed, the domains will belong to client with login name "sir_robert".
<packet version="1.5.2.0"> <migration> <start> <host>192.0.2.221</host> <login>admin</login> <password>jkSGtvbg55</password> <source-host-directory/> <destination-host-directory/> <system-type>unix</system-type> <selected-objects> <migrate-domains> <target-client>sir_robert</target-client> <domain> <name>rustyart.org</name> </domain> <domain> <name>grungyart.org</name>

Supported Operations </domain> </migrate-domains> </selected-objects> </start> </migration> </packet>

1343

1.3. Migrating multiple domains to multiple client accounts This packet starts migration of three domains called meaning-of-life.net, holy-grail.net and gold-member.net from server running Microsoft Windows. After the migration, the first two domains will belong to client with login name "monty_python", and the last, to client with login "austin_powers".
<packet version="1.5.2.0"> <migration> <start> <host>192.0.2.200</host> <login>admin</login> <password>jkSGtvbg55</password> <source-host-directory/> <destination-host-directory/> <system-type>windows</system-type> <selected-objects> <migrate-domains> <target-client>monty_python</target-client> <domain> <name>meaning-of-life.net</name> </domain> <domain> <name>holy-grail.net</name> </domain> </migrate-domains> <migrate-domains> <target-client>monty_python</target-client> <domain> <name>meaning-of-life.net</name> </domain> </migrate-domains> </selected-objects> </start> </migration> </packet>

1344

Supported Operations

2. Starting migrations in Plesk for Unix 2.1. Migrating a single domain account This packet starts migration of domain called samples.org, with mapping rules for the IP address on which the domain is hosted and for two databases (MySQL and PostgreSQL) used on the domain. When the migration is completed, the domain will belong to client with login name "joseph_williams".
<packet version="1.4.2.0"> <migration> <start> <host>212.58.49.220</host> <login>admin</login> <password>jkSGtvbg55</password> <source-host-directory>/tmp</source-host-directory> <destination-host-directory>/tmp</destination-host-directory> <selected-objects> <migrate-domains> <target-client>joseph_williams</target-client> <domain> <name>samples.org</name> <ip> <old> <ip-type>shared</ip-type> <ip-address>212.58.49.228</ip-address> </old> <new> <ip-type>shared</ip-type> <ip-address>212.58.49.15</ip-address> </new> </ip> <db-server> <old> <host>localhost</host> <port>3306</port> <type>mysql</type> </old> <new> <host>mysql3</host> <port>3306</port> <type>mysql</type> </new> </db-server> <db-server> <old> <host>localhost</host> <port>5432</port> <type>postgresql</type> </old> <new> <host>localhost</host> <port>5432</port> <type>postgresql</type> </new> </db-server> </domain> </migrate-domains> </selected-objects></start></migration></packet>

Supported Operations

1345

2.2. Migrating multiple domains to a single client account This packet starts migration of domains called rustyart.org and grungyart.org. When the migration is completed, the domains will belong to client with login name "sir_robert".
<packet version="1.4.2.0"> <migration> <start> <host>212.58.49.220</host> <login>admin</login> <password>jkSGtvbg55</password> <source-host-directory>/tmp</source-host-directory> <destination-host-directory>/tmp</destination-host-directory> <selected-objects> <migrate-domains> <target-client>sir_robert</target-client> <domain> <name>rustyart.org</name> </domain> <domain> <name>grungyart.org</name> </domain> </migrate-domains> </selected-objects> </start> </migration> </packet>

2.3. Migrating domains to multiple client accounts This packet starts migration of three domains called meaning-of-life.net, holy-grail.net and gold-member.net. After the migration, the first two domains will belong to client with login name "monty_python", and the last, to client with login "austin_powers".
<packet version="1.4.2.0"> <migration> <start> <host>212.58.49.220</host> <login>admin</login> <password>jkSGtvbg55</password> <source-host-directory>/tmp</source-host-directory> <destination-host-directory>/tmp</destination-host-directory> <selected-objects> <migrate-domains> <target-client>monty_python</target-client> <domain> <name>meaning-of-life.net</name> </domain> <domain> <name>holy-grail.net</name> </domain> </migrate-domains> <migrate-domains> <target-client>monty_python</target-client> <domain> <name>meaning-of-life.net</name> </domain> </migrate-domains> </selected-objects> </start></migration></packet>

1346

Supported Operations

Response Packet Structure


The start node of the response packet is structured as follows:

The result node is required. It wraps the result of the start operation. Data type: MigrationOutputStartResultType (plesk_migration.xsd). The status node is required. It returns the execution status of the start operation. Data type: string. Allowed values: ok | error. The errcode node is required if the operation fails. It returns the error code when the start operation fails. Data type: unsignedInt. The errtext node is required if the operation fails. It returns the error message if the start operation fails. Data type: string. The migration_id node is required in Plesk for Unix if the start operation succeeds. It returns the unique identifier of the migration that has just been started. Data type: string.

Supported Operations

1347

Response Samples
A positive response received from a Plesk for Unix server can look as follows:
<packet version="1.4.2.0"> <migration> <start> <result> <status>ok</status> <migration_id>/opt/psa/tmp/supervisor.24174</migration_id> </result> </start> </migration> </packet>

Positive responses received from a Plesk for Windows server looks as follows:
<packet version="1.5.2.0"> <migration> <start> <result> <status>ok</status> </result> </start> </migration> </packet>

Negative Response Samples The following responses are received if the request packet sent to the server intended to start a migration of a client or a domain with name that already exists in the destination Plesk. Client exists in Plesk for Unix
<packet version="1.4.2.0"> <migration> <start> <result> <status>error</status> <errcode>15012</errcode> <errtext>Client with login name "jimmy_jones" already exists.</errtext> </result> </start> </migration> </packet>

1348

Supported Operations

Client exists in Plesk for Windows


<packet version="1.5.2.0"> <migration> <start> <result> <status>error</status> <errcode>1007</errcode> <errtext>Client already exists.</errtext> </result> </start> </migration> </packet>

Domain exists in Plesk for Unix


<packet version="1.4.2.0"> <migration> <start> <result> <status>error</status> <errcode>15006</errcode> <errtext>Domain "jimmyjones.com" already exists on the destination server, or domain name is invalid</errtext> </result> </start> </migration> </packet>

Domain exists in Plesk for Windows


<packet version="1.5.2.0"> <migration> <start> <result> <status>error</status> <errcode>1007</errcode> <errtext>Domain "jimmyjones.com" already exists on the destination server, or domain name is invalid</errtext> </result> </start> </migration> </packet>

Such response is received from Plesk for Windows server if the request packet defined a wrong type of OS running on the source server.
<packet version="1.5.2.0"> <migration> <start> <result> <status>error</status> <errcode>1019</errcode> <errtext>Wrong system type</errtext> </result> </start> </migration> </packet>

Supported Operations

1349

Such response is received if the request packet sent to the server intended to start domain migration and contained a non-existent client account specified in the targetclient node.
<packet version="1.4.2.0"> <migration> <start> <result> <status>error</status> <errcode>15011</errcode> <errtext>The target client "joseph_williams" does not exist on the destination host</errtext> </result> </start> </migration> </packet>

Such response is received if the request packet sent to the server intended to start a migration with IP mapping rules in which a non-existent destination IP was specified.
<packet version="1.4.2.0"> <migration> <start> <result> <status>error</status> <errcode>15007</errcode> <errtext>IP "192.0.2.1" does not exist on the destination host</errtext> </result> </start> </migration> </packet>

Such response is received if the request packet sent to the server intended to start a migration with IP mapping rules in which wrong IP type was specified.
<packet version="1.4.2.0"> <migration> <start> <result> <status>error</status> <errcode>15009</errcode> <errtext>On the destination host, IP "192.0.2.1" type is "exclusive", not "shared"</errtext> </result> </start> </migration> </packet>

1350

Supported Operations

Retrieving Migration Status


After starting a migration, you can get information on its current status by sending a request packet with the get_status operation node, which should also include the migration unique identifier (see page 1346) returned by the start operation. Since Plesk for Windows Migration Manager can perform only one migration at a time, it doesn't need migration ID value to correctly retrieve the current migration status.

In this section:
Request Packet Structure And Samples............................................................ 1350 Response Packet Structure ............................................................................... 1352 Response Samples ........................................................................................... 1354

Request Packet Structure And Samples


A request XML packet retrieving information on the migration status includes the get_status operation node:
<packet version="1.4.2.0"> <migration> <get_status> </get_status> </migration> </packet>

The get_status node is presented by complex type MigrationId (migration_input.xsd), and its graphical representation is as follows:

The migration_id node is required. It holds the unique identifier of the migration. Data type: none. In Plesk for Windows, the node value must be any string.

With one get_status operation, you can get information on the progress of a single migration. To retrieve information on multiple migrations with one packet, use the required number of the get_status nodes in your request packet. In case of Plesk for Windows Migration Manager, with the get_status operation you get information on the status of the currently run migration.

Supported Operations

1351

This packet retrieves the status of migration performed by the Plesk for Windows server.
<packet version="1.5.2.0"> <migration> <get_status> <migration_id>1</migration_id> </get_status> </migration> </packet>

This packet retrieves from the Plesk for Unix server the status of the migration with ID /opt/psa/tmp/supervisor.24174.
<packet version="1.4.2.0"> <migration> <get_status> <migration_id>/opt/psa/tmp/supervisor.24174</migration_id> </get_status> </migration> </packet>

This packet retrieves from the Plesk for Unix server the status of migrations with ID /opt/psa/tmp/supervisor.24175 and /opt/psa/tmp/supervisor.24176.
<packet version="1.4.2.0"> <migration> <get_status> <migration_id>/opt/psa/tmp/supervisor.24175</migration_id> </get_status> <get_status> <migration_id>/opt/psa/tmp/supervisor.24176</migration_id> </get_status> </migration> </packet>

1352

Supported Operations

Response Packet Structure


The get_status node of the response packet is structured as follows:

The result node is required. It wraps the result of the get_status operation. Data type: MigrationOutputGetStatusResultType (migration_agent_output.xsd). The status node is required. It returns the execution status of the get_status operation. Data type: string. Allowed values: ok | error. The errcode node is required if the operation fails. It returns the error code when the get_status operation fails. Data type: unsignedInt. The errtext node is required if the operation fails. It returns the error message if the get_status operation fails. Data type: string.

The migration_status node is required if the get_status operation succeeded and the migration is still in progress. It holds the collection of data describing the current status of the migration. Data type: MigrationStatus (plesk_migration.xsd). The total node is required if the get_status operation succeeded and the migration is still in progress. It holds the number of all the internal items which are involved in the process of migration. The more objects are migrated, the bigger value is returned by the total node. Data type: integer. The completed node is required if the get_status operation succeeded and the migration is still in progress. It specifies how many migration items out of the total have already been migrated. Data type: integer.

Supported Operations

1353

The description node is optional. It returns description of the current migration step if this information is available. Data type: string. The finished node is required if the get_status operation succeeded and the migration has been finished. In API RPC v.1.5.0.0 and earlier, the node value type is string (indicating that the migration has been finished successfully). In API RPC v.1.5.1.0 and later, the finished node is of MigrationFinishedType (migration_output.xsd) and has the following graphical representation:

The success node is optional. It is present in a response packet if the operation succeeded. Data type: none. The error node is optional. If an error occurs during the migration, it contains the error details. Data type: ErrorType (migration_output.xsd). The following nodes are required only in case of a migration error occurrence: The object node is optional. It contains type of the object caused the error. Data type: ObjectErrorType (migration_output.xsd). The type node is optional. It contains type of the object caused the error. Data type: string. The name node is optional. It contains name of the object caused the error. Data type: string. The message node is oprional. It contains the error message. Data type: string.

1354

Supported Operations

Response Samples
Positive Responses A response received from server where migration is running can look as follows:
<packet version="1.5.2.0"> <migration> <get_status> <result> <status>ok</status> <migration_status> <total>33</total> <completed>10</completed> </migration_status> </result> </get_status> </migration> </packet>

Responses received from server where migration is successfully finished look as follows:
<packet version="1.4.2.0"> <migration> <get_status> <result> <status>ok</status> <finished></finished> </result> </get_status> </migration> </packet>

<packet version="1.5.2.0"> <migration> <get_status> <result> <status>ok</status> <finished> <success/> </finished> </result> </get_status> </migration> </packet>

Supported Operations

1355

A response received from server where migration is finished with errors can look as follows:
<packet version="1.5.2.0"> <migration> <get_status> <result> <status>ok</status> <finished> <error> <object> <type>domain</type> <name>example.com</name> </object> <message>Error in physical hosting updating: permission denied</message> </error> </finished> </result> </get_status> </migration> </packet>

Negative Responses Negative response received from server can look as follows.
<packet version="1.5.2.0"> <migration> <get_status> <result> <status>error</status> <errcode>1013</errcode> <errtext>Session with ID "/opt/psa/tmp/24174" does not exist</errtext> </result> </get_status> </migration> </packet>

1356

Supported Operations

Stopping Migration
To stop migration running at the moment, use the FINISH operation. If the operation is successful, the migration is immediately stopped, and all the data related to the migration (that is, dumps on source and destination servers, migration log file) is deleted. If the FINISH operation is performed at the moment when some of the migrated objects have already been deployed to the destination Plesk, the migration will be stopped, migration dumps and log files will be deleted, but the objects deployed will remain in Plesk.

In this section:
Request Packet Structure And Samples............................................................ 1356 Response Packet Structure And Samples ......................................................... 1358

Request Packet Structure And Samples


A request XML packet stopping the migration includes the finish operation node:
<packet version="1.4.2.0"> <migration> <finish> </finish> </migration> </packet>

The finish node is presented by complex type MigrationId (plesk_migration.xsd), and its graphical representation is as follows:

The migration_id node is required. It holds the unique identifier of the migration. Data type: none. In Plesk for Windows, the node value must be any string.

With one finish operation, you can stop only a single migration. To stop multiple migrations with one packet, use the required number of the finish nodes in your request packet. In case of Plesk for Windows, with the finish operation you stop the current migration.

Supported Operations

1357

This packet stops the current migration performed by Plesk for Windows Migration Manager.
<packet version="1.5.2.0"> <migration> <finish> <migration_id>1</migration_id> </finish> </migration> </packet>

This packet stops the migration with ID /opt/psa/tmp/supervisor.24174.


<packet version="1.5.2.0"> <migration> <finish> <migration_id>/opt/psa/tmp/supervisor.24174</migration_id> </finish> </migration> </packet>

This packet stops migrations with ID /opt/psa/tmp/supervisor.24175 and /opt/psa/tmp/supervisor.24176.


<packet version="1.5.2.0"> <migration> <finish> <migration_id>/opt/psa/tmp/supervisor.24175</migration_id> </finish> <finish> <migration_id>/opt/psa/tmp/supervisor.24176</migration_id> </finish> </migration> </packet>

1358

Supported Operations

Response Packet Structure And Samples


The finish node of the response packet is structured as follows:

The result node is required. It wraps the result of the get_status operation. Data type: resultType. The status node is required. It returns the execution status of the finish operation. Data type: string. Allowed values: ok | error. The errcode node is optional. It returns the error code when the finish operation fails. Data type: unsignedInt. The errtext node is optional. It returns the error message if the finish operation fails. Data type: string.

Response Samples Positive responses received from server look as follows:


<packet version="1.5.2.0"> <migration> <finish> <result> <status>ok</status> </result> </finish> <finish> <result> <status>ok</status> </result> </finish> </migration> </packet>

Supported Operations

1359

A negative response received from server can look as follows:


<packet version="1.5.2.0"> <migration> <finish> <result> <status>error</status> <errcode>1013</errcode> <errtext>Session with ID "/opt/psa/tmp/24174" does not exist</errtext> </result> </finish> </migration> </packet>

1360

Supported Operations

Retrieving Action Log Data


Operator: <event_log> XML Schema:event_log_input.xsd, event_log_output.xsd Plesk version: all versions API RPC version: 1.4.0.0 and higher Plesk user: Plesk Administrator Description Plesk keeps track of actions performed by all Plesk users. The list of actions is called Action log. Use the event_log operator to retrieve Action log. Supported operations:

GET_EVENTS (see page 1361) retrieves part of the log from the specified event ID and later GET-LAST-ID (see page 1366) retrieves ID of the last action

Note: The get-last-id operation is supported starting with API RPC protocol v.1.4.2.0.

In this section:
Retrieving Action Log ........................................................................................ 1361 Retrieving ID of Last Action ............................................................................... 1366

Supported Operations

1361

Retrieving Action Log


Use the get-events operation to retrieve the Action log starting from a specified action. For information on retrieving the ID of last action, refer to the Retrieving ID of Last Action (see page 1366) section. If you interact with Plesk 9 through API RPC 1.5.2.1 and earlier versions, each resellerrelated action will be tracked as a client-related action. The following table summarizes the mapping of reseller-related actions to client-related actions.
Action Name in Plesk 9 Object Class Event Type

Reseller account created Reseller limit updated Reseller status changed

client client_limits client

created updated status_changed updated updated updated exceeded exceeded deleted

Reseller preferences changed client_prefs Reseller permissions changed Reseller's IP pool changed Reseller exceeds traffic limit Reseller exceeds size limit Reseller account removed client_perms client_ip_pool client_limit_traffic client_limit_size client

In this section:
Request Packet ................................................................................................. 1362 Response Packet Structure ............................................................................... 1363 Response Samples ........................................................................................... 1365

1362

Supported Operations

Request Packet
A request XML packet retrieving actions log includes the get_events node:
<packet version="1.4.2.0"> <event_log> <get_events> ... </get_events> </event_log> </packet>

The get_events node has the following graphical representation:

The lastId node is optional. It specifies the ID of an action to start from. Data type: integer.

Note: To retrieve all actions performed on the server, do not specify this node. Request packet samples This packet retrieves the Action log starting from the action with ID 177.
<packet version="1.4.2.0"> <event_log> <get_events> <lastId>177</lastId> </get_events> </event_log> </packet>

This packet retrieves the Action log (from action ID 0).


<packet version="1.4.2.0"> <event_log> <get_events/> </event_log> </packet>

Supported Operations

1363

Response Packet Structure


The get_events node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get_events operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get_events operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get_events operation fails. Data type: string. The event node is optional. It contains an action data if the operation succeeds, and the list of retrieved actions is not empty. Data type: complex.

1364

Supported Operations

The following nodes are required only if the event node is present in the response packet: The id node is required. It holds action ID. Data type: integer. The type node is required. It specifies the type of the action. Data type: string. Allowed values: created | updated | deleted | status_changed | started | stopped | installed | uninstalled | siteapp_added | siteapp_removed | expired | terminated | exceeded | guid_changed.

Note: The guid_changed type is available in API RPC 1.5.2.0 and later versions. The time node is required. It specifies time when the action happened (in Unix timestamp). Data type: unsignedint. The class node is required. It specifies the class of object that performed the action. Data type: string. Allowed values: license | service | ip_address | admin_info | siteapp | client | client_limits | client_status | client_prefs | client_perms | client_ip_pool | db | db-user| domain | domain_limits | domain_user| domain_status | phosting | fhosting | subdomain | mailname | webuser | maillist | dns_zone | mailname_antivirus | mailname_spamfilter | mailname_mailgroup | mailname_autoresponder | mailname_attachment | session_preferences | db_server | domain_alias | remote_dns | dashboard_preset | dashboard_preset_type | dashboard_preset_name | domain_limit_size | client_limit_size | client_limit_traffic | domain_limit_traffic | plesk_component reseller | reseller_limits | reseller_status | reseller_prefs | reseller_perms | reseller_ip_pool | reseller_limit_size | reseller_limit_traffic

Note: The plesk_component class is available in API RPC 1.5.1.0 and later versions. Classes db and db-user are available in API RPC 1.5.2.0 and later versions. Classes reseller_* are available since API RPC 1.6.0.0. The obj_id node is required. It specifies the unique field of an object that performed the action. Data type: string. The user node is required. It specifies the login name of a user who performed the action. Data type: string.

The host node is required. It specifies the IP address of a host from which the action was performed. Data type: string

Supported Operations

1365

Response Samples
Request sample This packet retrieves the Action log starting from the action with ID 177.
<packet version="1.4.2.0"> <event_log> <get_events> <lastId>177</lastId> </get_events> </event_log> </packet>

Response sample A possible response from the server can look as follows:
<packet version="1.4.2.0"> <event_log> <get_events> <result> <status>ok</status> <event> <id>177</id> <type>updated</type> <time>1165055109</time> <class>dns_zone</class> <obj_id>Mydomain.com</obj_id> <user>myUser</user> <host>192.168.56.53</host> </event> <event> <id>178</id> <type>created</type> <time>1165055209</time> <class>mailname</class> <obj_id>mail@Mydomain.com</obj_id> <user>myUser</user> <host>192.168.56.53</host> </event> </result> </get_events> </event_log> </packet>

1366

Supported Operations

If the ID is more than last operation ID, the response looks as follows:
<packet version="1.4.2.0"> <event_log> <get_events> <result> <status>ok</status> </result> </get_events> </event_log> </packet>

Retrieving ID of Last Action


Use the get-last-id operation to retrieve the ID of the last action performed on the server. Note: The get-last-id operation is supported starting with API RPC protocol v.1.4.2.0.

In this section:
Request Packet ................................................................................................. 1366 Response Packet Structure ............................................................................... 1367 Response Samples ........................................................................................... 1367

Request Packet
A request XML packet retrieving the last action ID includes the get-last-id node:
<packet version="1.4.2.0"> <event_log> <get-last-id> ... </get-last-id> </event_log> </packet>

The get-last-id node has the following graphical representation:

Data type: none. Request packet sample This packet retrieves the last action ID.
<packet version="1.4.2.0"> <event_log> <get-last-id/> </event_log></packet>

Supported Operations

1367

Response Packet Structure


The get-last-id node of the output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the get-last-id operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the get-last-id operation fails. Data type: integer. The errtext node is optional. It returns the error message if the get-last-id operation fails. Data type: string. The id node is optional. It holds the last action ID. Data type: integer.

Response Samples
Request packet sample This request packet retrieves the last action ID.
<packet version="1.4.2.0"> <event_log> <get-last-id/> </event_log> </packet>

A possible response from the server can look as follows:


<packet version="1.4.2.0"> <event_log> <result> <status>ok</status> <id>178</id> </result> </event_log> </packet>

1368

Supported Operations

Uploading Files to Server


Operator: <upload> XML Schema: upload_output.xsd Plesk version: Plesk 7.5.3 for Unix and later API RPC version: 1.3.5.0 and higher Plesk user: Plesk Administrator Description This operator is used to upload files to Plesk. Unlike other operators, the upload operator does not use a standard request packet structure. Instead of it, the upload uses the POST method http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html to upload files. When a request is processed by Plesk, the response is given in the packet structured as in the XML schema. After a file is uploaded to Plesk, it can be used in other operations. If it is a site package application, it can be installed (see page 1106) using the siteapp operator. Note: You can also upload files using FTP managers.

In this section:
Uploading Files Using cURL .............................................................................. 1368 Uploading Files Using PHP ............................................................................... 1370 Uploading Files Using .NET .............................................................................. 1371 Response Packet Structure ............................................................................... 1375 Response Samples ........................................................................................... 1376

Uploading Files Using cURL


To upload a file perform the following steps: 1. Create a SSH connection to the Unix server where the file is located. 2. Type the following string in the Unix shell:
curl -k -F myfile=@install.log -H 'HTTP_AUTH_LOGIN:admin' -H 'HTTP_AUTH_PASSWD:password' https://Plesk_IP:8443/enterprise/control/a gent.php.

Arguments
curl Specifies that cURL http://curl.haxx.se/ is used. You need to install it to the Unix machine. -k

Supported Operations

1369

The SSL connection is used. -F myfile=@install.l og The install.log file is to be uploaded. You can upload multiple files in a single packet. -H 'HTTP_AUTH_LOGIN:adm in' Specifies the login of the administrator of Plesk server. Substitute the admin value by your login to Plesk Server. -H 'HTTP_AUTH_PASSWD:p assword' Specifies the password of the administrator of Plesk server. Substitute the password value by your password to Plesk Server. https://Plesk_IP:8443/enterprise/ control/agent.php Specifies the address of Plesk server. Substitute the Plesk_IP value by the IP address of the server.

3. Press ENTER.

1370

Supported Operations

Uploading Files Using PHP


This is a sample of PHP script uploading files to Plesk. Change HOST, LOGIN, PASSWD, and FILENAME with credentials of your Plesk server. HOST LOGIN PASSWD FILENAME The IP address or name of the Plesk server. Login name of the Plesk Administrator. Password of the Plesk Administrator. Full name of the file to be uploaded.

<?php define("HOST", "10.58.97.31"); define("PATH", "/enterprise/control/agent.php"); define("LOGIN", "admin"); define("PASSWD", 'setup'); define("FILENAME", '../../data.rpm'); function write_callback($ch, $data) { echo $data; return strlen($data); } function uploadFile($filename) {$url = "https://" . HOST . ":8443" . PATH; $headers = array( "HTTP_AUTH_LOGIN: " . LOGIN, "HTTP_AUTH_PASSWD: " . PASSWD, "HTTP_PRETTY_PRINT: TRUE", "Content-Type: multipart/form-data;", ); // Initialize the curl engine $ch = curl_init(); // Set the curl options curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); // this line makes it work under https curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // Set the URL to be processed curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_POSTFIELDS, array ('sampfile'=>"@$filename")); $result = curl_exec($ch); if (curl_errno($ch)) { echo "\n\n-------------------------\n" . "cURL error number:" . curl_errno($ch); echo "\n\ncURL error:" . curl_error($ch);

Supported Operations } curl_close($ch); //fclose($fp); return; } uploadFile(realpath(FILENAME)); ?>

1371

Uploading Files Using .NET


This .NET source code uploads files to Plesk. Change values of the Hostname, Login, Password, and Protocol variables with parameters of your Plesk server. Change value of the Filename variable with full name of the file you want to upload. Filename Hostname Login Password Protocol Full name of the file to be uploaded. The IP address or name of the Plesk server. Login name of the Plesk Administrator. Password of the Plesk Administrator. Version of the protocol.

using System; using System.Net; using System.Text; using System.IO; using System.Xml; using System.Xml.Schema; using System.Security.Cryptography.X509Certificates; using System.Net.Security; namespace ConsoleApplication1 { public class Request { // Public interface // public string Filename = "./tmp/myfile.sh"; // Upload file name; public string Hostname = "localhost"; // Control Panel Hostname public string Login = "admin"; // Administrator Login public string Password = "setup"; // Administrator Password public string Protocol = "1.4.2.0"; // API RPC Version Protocol. Now avaiable the followings: // 1.3.5.1 // 1.4.0.0 // 1.4.1.0 // 1.4.1.1 // 1.4.1.2

1372

Supported Operations // 1.4.2.0

// Handler for receiving information about document type definition (DTD), // XML-Data Reduced (XDR) schema, and XML Schema definition language (XSD) schema validation errors. public ValidationEventHandler XmlSchemaValidation = null; public Request() { } public string AgentEntryPoint { get { return "https://" + Hostname + ":8443/enterprise/control/agent.php"; } } public string InputValidationSchema { get { return "https://" + Hostname + ":8443/schemas/rpc/" + Protocol + "/agent_input.xsd"; } } public string OutputValidationSchema { get { return "https://" + Hostname + ":8443/schemas/rpc/" + Protocol + "/agent_output.xsd"; } } public XmlDocument UploadFile(string uploadfile) { HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AgentEntryPoint); string boundary = "----------" + DateTime.Now.Ticks.ToString("x"); request.Headers.Add("HTTP_AUTH_LOGIN", Login); request.Headers.Add("HTTP_AUTH_PASSWD", Password); request.ContentType = "multipart/form-data; boundary=" + boundary; request.Method = "POST"; // Build up the post message header StringBuilder sb = new StringBuilder(); sb.Append("--"); sb.Append(boundary); sb.Append("\r\n"); sb.Append("Content-Disposition: form-data; name=\""); sb.Append("sampfile"); sb.Append("\"; filename=\""); sb.Append(Path.GetFileName(uploadfile)); sb.Append("\""); sb.Append("\r\n"); sb.Append("Content-Type: "); sb.Append("application/octet-stream"); sb.Append("\r\n"); sb.Append("\r\n"); string postHeader = sb.ToString(); byte[] postHeaderBytes = Encoding.UTF8.GetBytes(postHeader); // Build the trailing boundary string as a byte array // ensuring the boundary appears on a line by itself byte[] boundaryBytes = Encoding.ASCII.GetBytes("\r\n--" + boundary + "\r\n"); FileStream fileStream = new FileStream(uploadfile, FileMode.Open, FileAccess.Read); long length = postHeaderBytes.Length + fileStream.Length + boundaryBytes.Length; request.ContentLength = length; Stream stream = request.GetRequestStream(); stream.Write(postHeaderBytes, 0, postHeaderBytes.Length); // Write out the file contents byte[] buffer = new Byte[checked((uint)Math.Min(4096, (int)fileStream.Length))]; int bytesRead = 0;

Supported Operations

1373

while ((bytesRead = fileStream.Read(buffer, 0, buffer.Length)) != 0) stream.Write(buffer, 0, bytesRead); // Write out the trailing boundary stream.Write(boundaryBytes, 0, boundaryBytes.Length); XmlDocument result = GetResponse(request); return result; } // Private interface // // Parsing and validating packet // private XmlDocument ParseAndValidate(TextReader xml, string schemaUri) { XmlSchemaSet schemas = new XmlSchemaSet(); schemas.Add(null, schemaUri); XmlReaderSettings settings = new XmlReaderSettings(); if (XmlSchemaValidation != null) settings.ValidationEventHandler += new ValidationEventHandler(XmlSchemaValidation); settings.ValidationType = ValidationType.Schema; settings.ValidationFlags |= XmlSchemaValidationFlags.ProcessSchemaLocation; settings.Schemas = schemas; XmlDocument document = new XmlDocument(); using (XmlReader reader = XmlTextReader.Create(xml, settings)) { document.Load(reader); } return document; } private XmlDocument GetResponse(HttpWebRequest request) { using (HttpWebResponse response = (HttpWebResponse)request.GetResponse()) using (Stream stream = response.GetResponseStream()) using (TextReader reader = new StreamReader(stream)) { return ParseAndValidate(reader, OutputValidationSchema); } } } class Program { static void Main(string[] args) { if (args.Length < 4) { Console.WriteLine("Usage: PleskApiRpcClient <Hostname> <Login> <Password> <FileName>"); Console.WriteLine(" "); Console.WriteLine(" Hostname - Control Panel hostname"); Console.WriteLine(" Login - Administrator login");

1374

Supported Operations Console.WriteLine(" Password - Administrator password"); Console.WriteLine(" FileName - Upload file name"); return; } // Verifies the remote Secure Sockets Layer (SSL) certificate used for authentication. ServicePointManager.ServerCertificateValidationCallback = new RemoteCertificateValidationCallback(RemoteCertificateValidation); Request request = new Request(); request.XmlSchemaValidation = XmlSchemaValidation; try { XmlDocument result = request.UploadFile(filename); PrintResult(result); } catch (Exception e) { Console.WriteLine("Request error: {0}", e.Message); } } // The following method is invoked by the RemoteCertificateValidationDelegate. private static bool RemoteCertificateValidation(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors) { if (sslPolicyErrors != SslPolicyErrors.RemoteCertificateNotAvailable) return true; Console.WriteLine("Certificate error: {0}", sslPolicyErrors); // Do not allow this client to communicate with unauthenticated servers. return false; } // private static void XmlSchemaValidation(object sender, ValidationEventArgs e) { Console.WriteLine("Validation error: {0}", e.Message); } static void PrintResult(XmlDocument document) { XmlTextWriter writer = new XmlTextWriter(Console.Out); writer.Formatting = Formatting.Indented; document.WriteTo(writer); writer.Flush(); Console.WriteLine(); } } }

Supported Operations

1375

Response Packet Structure


The upload output XML packet is structured as follows:

The result node is required. It wraps the response retrieved from the server. Data type: resultType (common.xsd). The status node is required. It specifies the execution status of the upload operation. Data type: string. Allowed values: ok | error. The errcode node is optional. Is returns the error code if the upload operation fails. Data type: integer. The errtext node is optional. It returns the error message if the upload operation fails. Data type: string. The name node is required. Specifies the name of the uploaded file. Data type: string. The file node is required. Specifies full name of the temporary file. Data type: string.

1376

Supported Operations

Response Samples
Uploading a single package If an agent requested to upload the li.sh package to Plesk server, the positive response from the server looks as follows:
<packet version="1.3.4.0"> <upload> <result> <status>ok</status> <name>myfile</name> <file>/usr/local/psa/tmp/li.sh</file> </result> </upload> </packet>

If the uploaded file exceeds the upload_max_filesize directive set in php.ini, the response from the server looks as follows:
<packet version="1.3.4.0"> <upload> <result> <status>error</status> <errcode>1023</errcode> <errtext>The uploaded file exceeds the upload_max_filesize directive set in php.ini</errtext> <name>myfile</name> <file>/usr/local/psa/tmp/li.sh</file> </result> </upload> </packet>

Uploading multiple packages If an agent requested to upload li.sh and mybox.sh files to Plesk server, the positive response from the server looks as follows:
<packet version="1.3.4.0"> <upload> <result> <status>ok</status> <name>myfile</name> <file>/usr/local/psa/tmp/li.sh</file> </result> <result> <status>ok</status> <name>mybox</name> <file>/usr/local/psa/tmp/mybox.sh</file> </result> </upload> </packet>

CHAPTER 7

Error Codes
This section presents all error codes that can appear, and their descriptions as well. When a request packet arrives at Plesk API RPC server, it is validated, after which the requested operation performs. If any of these actions fail, Plesk sends back a response packet with an error code. For example:
<packet version=1.4.1.2> <domain> <get> <result> <status>error</status> <errcode>1013</errcode> <errtext>Object not found.</errtext> <id>1234</id> </result> </get> </domain> </packet>

The error code passed in the errcode node is described in the errtext node. At present, Plesk supports two sets of error codes: Starting with versions 8.0 for UNIX / 7.6.1 for Windows, Plesk supports a reduced set of error codes. To learn more about the reduced set of error codes, refer to the Reduced List of Error Codes (see page 1377) section. The complete set of error codes is supported by earlier versions of Plesk (prior to Plesk 8.0 for UNIX / Plesk 7.6 for Windows). It provides a detailed collection of error codes for each Plesk object (Client, Domain, DNS, etc.). To learn more, refer to the Complete List of Error Codes (on page 1379) section.

In this chapter:
Reduced List of Error Codes ..............................................................................1377 Complete List of Error Codes .............................................................................1379

1378

Error Codes

Reduced List of Error Codes


This section contains the reduced list of error codes which is supported by Plesk 8.0 for UNIX / Plesk 7.6 for Windows and later.
ERROR CODE 1001 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1017 1018 1019 1023 1024 1025 1026 1027 1029 1030 1031 1032 1033 1050 11003 14008 DESCRIPTION Authentication failed - wrong password. Agent initialization failed. Plesk initial setup not completed. API RPC version not supported. Permission denied. Inserted data already exists. Multiple access denied. Invalid Virtuozzo key. Access to Plesk Panel denied. Account disabled. Locked login. Object does not exist/Unknown service. Parsing error: wrong format of XML request. Object owner not found. Feature not supported by the current version of API RPC. IP address not found. Invalid value. Operation failed. Limit reached. Wrong status value. Component not installed. IP operation failed. Unknown authentication method. License expired. Component not configured. Wrong network interface. Client account is incomplete (important fields are empty). Webmail not installed. Secret key validation failed. Wrong database server type.

Error Codes

1379

14009

Database server not configured.

Complete List of Error Codes


This section contains a complete list of error codes supported by earlier versions of Plesk (prior to Plesk 8.0 for UNIX / Plesk 7.6.1 for Windows). Plesk API RPC server reports about errors that occur during the execution of your request as well as about syntactical errors in XML packets. The error code and the description message are sent back to the client software within a response packet structured as described in the Plesk API RPC Packet Structure section. All errors generated by Plesk API RPC server are grouped as follows:
RANGE 1000 - 1099 (see page 1383) 1100 1199 CLIENT OPERATIONS 1200 - 1299 (see page 1384) 1300 - 1399 (see page 1384) 1400 - 1499 (see page 1385) 1500 - 1599 (see page 1385) 1600 - 1999 DOMAIN OPERATIONS 2000 - 2099 (see page 1386) 2100 - 2199 (see page 1386) 2200 - 2299 (see page 1386) 2300 - 2399 (see page 1387) 2400 - 2499 (see page 1387) 2500 (see page 1387) 2501 - 2599 Delete domain operation errors Get domain operation errors Set domain operation errors Add domain operation errors Domain Buttons list operation errors Fetch data from DB operation error Reserved for future use Get client operation errors Set client operation errors Add client operation errors Client Buttons list operation errors Reserved for future use ERROR TYPE Common errors Reserved for future use

1380

Error Codes

2600 (see page 1388) 2601 - 2699 2700 (see page 1388) 2701 - 2999 IP OPERATIONS 3000 - 3099 (see page 1388) 3100 - 3199 (see page 1389) 3200 - 3299 (see page 1389) 3300 - 3399 (see page 1389) 3400 3999 DNS OPERATIONS 4000 - 4099 (see page 1390) 4100 - 4199 (see page 1390) 4200 - 4299 (see page 1390) 4300 (see page 1391) 4301 4399 4400 (see page 1391) 4401 4499 4500 (see page 1391) 4501-5499 4600 - 4699 (see page 1391) 4700-4999 SERVER OPERATIONS 5000 - 5099 (see page 1392) 5100 - 5199 (see page 1392) 5200 - 5299 (see page 1392)

Flush data to DB operation error Reserved for future use Webstat component error Reserved for future use

Delete IP operation errors Set IP errors Assign IP operation errors Unassign IP operation error Reserved for future use

Add DNS record operation errors Delete DNS record operation errors Get DNS record operation errors Get DNS ACL record operation error Reserved for future use Add DNS ACL record operation error Reserved for future use Remove DNS ACL record operation error Reserved for future use Set DNS record operation errors Reserved for future use

Set server password operation errors Set admin info operation errors Get admin info operation errors

Error Codes

1381

5300 - 5399 (see page 1393) 5400 - 5499 (see page 1393) 5500 (see page 1393) 5501 5599 5600 (see page 1393) 5601 5699 5700 (see page 1393) 5701 5799 5800 - 5899 (see page 1394) 5900 - 5999 SITEAPP OPERATIONS 6000 - 6099 (see page 1394) 6100 - 6999 EMAIL OPERATIONS 7000 - 7099 (see page 1395) 7100 - 7999

Service management errors Set server preferences operation errors Get additional key operation error Reserved for future use Set misc operation error Reserved for future use Get misc operation error Reserved for future use AE command processing errors Reserved for future use

SiteApp package management errors Reserved for future use

Email management errors Reserved for future use

CERTIFICATE OPERATIONS 8000 - 8099 (see page 1395) 8100 - 9000 UI OPERATIONS 9001 (see page 1396) 9002 - 9100 9101 (see page 1396) 9102 - 9200 9201 (see page 1396) 9202 - 9300 9301 (see page 1396) 9302 - 10000 Visibility customization error Reserved for future use Create custom button error Reserved for future use Get custom button error Reserved for future use Delete custom button error Reserved for future use Certificate management errors Reserved for future use

1382

Error Codes

UPLOAD OPERATIONS 10001 - 10099 (see page 1397) 10100 - 11000 Upload errors Reserved for future use

SECRET KEY OPERATIONS 11001 - 11100 (see page 1397) 11101 - 12000 Secret key management errors Reserved for future use

SPAM FILTER OPERATIONS 12001 - 12100 (see page 1398) 12101 - 13000 Spam filter management errors Reserved for future use

DOMAIN ALIAS OPERATIONS 13001 - 13100 (see page 1398) 13101 - 14000 Domain alias management errors Reserved for future use

DATABASE SERVER OPERATIONS 14001 - 14100 (see page 1399) 14101 - 14999 MIGRATION OPERATIONS 15000 - 15100 (see page 1399) Database server management errors Reserved for future use

Migration errors

Error Codes

1383

In this section:
Common errors ................................................................................................. 1383 Client Operations .............................................................................................. 1384 Domain Operations ........................................................................................... 1386 IP Operations .................................................................................................... 1388 DNS Operations ................................................................................................ 1390 Server Operations ............................................................................................. 1392 Web Application Operations .............................................................................. 1394 Email Operations ............................................................................................... 1395 Certificate Operations........................................................................................ 1395 UI Operations .................................................................................................... 1396 Upload Operations ............................................................................................ 1397 Secret Key Operations ...................................................................................... 1397 Spam Filter Operations ..................................................................................... 1398 Domain Alias Operations ................................................................................... 1398 Database Server Operations ............................................................................. 1399 Migration Operations ......................................................................................... 1399

Common errors
Range: 1000 1099
ERROR NUMBER 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1017 1018 DESCRIPTION Authentication failed - wrong password. Unknown/general internal error. Agent engine initialization error. Plesk initial setup not completed. API RPC protocol version not supported. Permission denied. The inserted data already exists. Multiple access denied. Invalid Virtuozzo key. Access to Plesk Panel denied. Account disabled. Login lock detected. Object does not exist/Unknown service. Request parsing error. Object owner not found. Feature not supported by Plesk API-RPC. IP does not exist.

1384

Error Codes

1019 1020 1021 1023 1024 1025 1026 1027 1028 1029 1030 1031 1034 1050

Invalid value. Invalid license. Failed to install the license key: the current use of control panel resources exceeds the limits set in the uploaded license key. Operation failed. Limit reached. Wrong status value. Component is not installed. Wrong IP address. Template not found. Unknown authentication method. License expired. Component is not configured on server. Operation failed: physical hosting is required. Webmail not installed.

Client Operations
In this section:
Get Client Operation Errors ............................................................................... 1384 Set Client Operation Errors ............................................................................... 1384 Add Client Operation Errors .............................................................................. 1385 Client Buttons List Operation Errors .................................................................. 1385

Get Client Operation Errors


Range: 1200 1299
ERROR NUMBER 1200 1201 DESCRIPTION Client not found. General get client operation error.

Error Codes

1385

Set Client Operation Errors


Range: 1300 1399
ERROR NUMBER 1300 1301 1302 1303 1304 1305 1306 1307 1308 DESCRIPTION General set client operation error. No client. Parsing error: wrong format of XML request. Object initialization error. Error while updating client. Failed to set permissions. Failed to set limits. Error while checking input data. Domain user with this client login already exist.

Add Client Operation Errors


Range: 1400 1499
ERROR NUMBER 1400 1401 1402 1403 1404 1405 DESCRIPTION General add client operation error. Parsing error: wrong format of XML request. Error while updating client. Failed to initialize 'add' operation. Failed to add permissions. Error while checking input data.

Client Buttons List Operation Errors


Range: 1500 1599
ERROR NUMBER 1500 DESCRIPTION General error while getting the form with the client buttons list.

1386

Error Codes

Domain Operations
In this section:
Delete Domain Operation Errors ....................................................................... 1386 Get Domain Operation Errors ............................................................................ 1386 Set Domain Operation Errors ............................................................................ 1386 Add Domain Operation Errors ........................................................................... 1387 Domain Buttons List Operation Errors ............................................................... 1387 Get_traffic Operation Error ................................................................................ 1387 Set_traffic Operation Error................................................................................. 1388 Webstat Component Error ................................................................................. 1388

Delete Domain Operation Errors


Range: 2000 2099
ERROR NUMBER 2000 2001 2002 DESCRIPTION Domain not found. Initialization error. General error.

Get Domain Operation Errors


Range: 2100 2199
ERROR NUMBER 2100 2101 DESCRIPTION Domain not found. Error while loading domain user.

Set Domain Operation Errors


Range: 2200 2299
ERROR NUMBER 2200 2201 2202 2203 2204 DESCRIPTION Error while setting up limits. Domain not found. Parsing error: wrong format of XML request. Initialization error. Hosting setup error.

Error Codes

1387

2205 2206 2207 2208

Limits setup error. User setup error. General data setup error. Client with this domain user login already exists.

Add Domain Operation Errors


Range: 2300 2399
ERROR NUMBER 2300 2301 2302 2303 2305 2306 2307 2308 DESCRIPTION General add domain operation error. Initialization error. Set client error. Error while getting IP. Requested domain IP does not belong to client. General error while setting object data. Hosting setup error. Limits setup error.

Domain Buttons List Operation Errors


Range: 2400 2499
ERROR NUMBER 2400 DESCRIPTION General error while getting the form with the domain buttons list.

Get_traffic Operation Error


Range: 2500
ERROR NUMBER 2500 DESCRIPTION General get_traffic operation error.

1388

Error Codes

Set_traffic Operation Error


Range: 2600
ERROR NUMBER 2600 DESCRIPTION General set_traffic operation error.

Webstat Component Error


Range: 2700
ERROR NUMBER 2700 DESCRIPTION The selected webstat component not supported.

IP Operations
In this section:
Delete IP Operation Errors ................................................................................ 1388 Set IP Operation Errors ..................................................................................... 1389 Assign IP Operation Errors ................................................................................ 1389 Unassign IP Operation Errors ............................................................................ 1389

Delete IP Operation Errors


Range: 3000 3099
ERROR NUMBER 3000 3001 3002 3003 DESCRIPTION Parsing error: wrong format of XML request. Error while initializing related object. IP not found. General delete IP error.

Error Codes

1389

Set IP Operation Errors


Range: 3100 3199
ERROR NUMBER 3100 3101 DESCRIPTION General set IP error. IP not found.

Assign IP Operation Errors


Range: 3200 3299
ERROR NUMBER 3200 3201 3202 3203 3204 3205 DESCRIPTION Parsing error: wrong format of XML request. Error while initializing related object. Error while adding IP to IP Pool. General assign IP error. General error while adding VZ IP. General error while adding a real IP.

Unassign IP Operation Errors


Range: 3300 3399
ERROR NUMBER 3300 3301 3302 3303 DESCRIPTION Parsing error: wrong format of XML request. Error while initializing related object. Error while adding IP to IP Pool. General unassign IP error.

1390

Error Codes

DNS Operations
In this section:
Add DNS Record Operation Errors .................................................................... 1390 Delete DNS Record Operation Errors ................................................................ 1390 Get DNS Record Operation Errors .................................................................... 1390 Get DNS ACL Record Operation Error .............................................................. 1391 Add DNS ACL Record Operation Error.............................................................. 1391 Remove DNS ACL Record Operation Error ....................................................... 1391 Set DNS Record Operation Errors..................................................................... 1391

Add DNS Record Operation Errors


Range: 4000 4099
ERROR NUMBER 4000 4001 4002 DESCRIPTION General add DNS record operation error. Parsing error: wrong format of XML request. Error while initializing related object.

Delete DNS Record Operation Errors


Range: 4100 4199
ERROR NUMBER 4100 4101 4102 4103 DESCRIPTION General delete DNS record operation error. Parsing error: wrong format of XML request. Error while initializing related object. DNS record not found.

Get DNS Record Operation Errors


Range: 4200 4299
ERROR NUMBER 4200 4201 4202 DESCRIPTION General get DNS record operation error. Parsing error: wrong format of XML request. Error while initializing related object.

Error Codes

1391

4203

DNS record not found.

Get DNS ACL Record Operation Error


Range: 4300
ERROR NUMBER 4300 DESCRIPTION General get DNS ACL record operation error.

Add DNS ACL Record Operation Error


Range: 4400
ERROR NUMBER 4400 DESCRIPTION General error while adding a record to DNS ACL (access control list).

Remove DNS ACL Record Operation Error


Range: 4500
ERROR NUMBER 4500 DESCRIPTION General error while removing a record from DNS ACL (access control list).

Set DNS Record Operation Errors


Range: 4600 4699
ERROR NUMBER 4600 4601 4602 4603 DESCRIPTION General set DNS record operation error. Parsing error: wrong format of XML request. Error while initializing related object. DNS record not found.

1392

Error Codes

Server Operations
In this section:
Set Server Password Operation Errors.............................................................. 1392 Set Admin Info Operation Errors........................................................................ 1392 Get Admin Info Operation Errors ....................................................................... 1392 Service Management Errors .............................................................................. 1393 Set Server Preferences Operation Errors .......................................................... 1393 Get Additional Key Operation Error ................................................................... 1393 Set Misc Operation Error ................................................................................... 1393 Get Misc Operation Error................................................................................... 1393 AE Command Processing Errors ....................................................................... 1394

Set Server Password Operation Errors


Range: 5000 5099
ERROR NUMBER 5000 5001 5002 5003 5004 5005 DESCRIPTION Parsing error: wrong format of XML request. Wrong password. Password setting error. Server initial setup error. Incorrect server name (full host name). Reconfiguration failed.

Set Admin Info Operation Errors


Range: 5100 5199
ERROR NUMBER 5100 5101 DESCRIPTION Parsing error: wrong format of XML request. Error while setting data.

Get Admin Info Operation Errors


Range: 5200 5299
ERROR NUMBER 5200 DESCRIPTION Service status checkup error.

Error Codes

1393

Service Management Errors


Range: 5300 5399
ERROR NUMBER 5300 DESCRIPTION General service management error.

Set Server Preferences Operation Errors


Range: 5400 5499
ERROR NUMBER 5400 5401 5402 DESCRIPTION General set server preferences operation error. License installation failed. General error while setting up session preferences.

Get Additional Key Operation Error


Range: 5500
ERROR NUMBER 5500 DESCRIPTION General error while getting an additional key.

Set Misc Operation Error


Range: 5600
ERROR NUMBER 5600 DESCRIPTION General set misc error.

Get Misc Operation Error


Range: 5700
ERROR NUMBER 5700 DESCRIPTION General et misc error.

1394

Error Codes

AE Command Processing Errors


Range: 5800 5899
ERROR NUMBER 5800 5801 5802 5803 5804 5805 DESCRIPTION General error while processing AE (authentication engine) command. Failed to enable AE. Failed to disable AE. Failed to get AE parameters. Failed to create AE session. Could not provide access to domain.

Web Application Operations


In this section:
Web Application Package Management Errors ................................................. 1394

Web Application Package Management Errors


Range: 6000 6099
ERROR NUMBER 6001 6002 6004 6005 6006 6007 6008 6009 DESCRIPTION Get all packages operation failed. Get packages by client operation failed. Add package operation failed. Get packages by domain operation failed. Get package requirements operation failed. General error while processing ser package properties operation. General error while installing a package. Remove package operation failed.

Error Codes

1395

Email Operations
In this section:
Email Management Errors ................................................................................. 1395

Email Management Errors


Range: 7000 7099
ERROR NUMBER 7001 7002 7003 7004 7005 7006 7007 DESCRIPTION Get info operation failed. Failed to enable email. Failed to disable email. Failed to remove email. Invalid document. Failed to create email. Failed to set email preferences.

Certificate Operations
In this section:
Certificate Management Errors .......................................................................... 1395

Certificate Management Errors


Range: 8000 8099
ERROR NUMBER 8001 8002 8003 8004 8005 8006 8007 DESCRIPTION Remove certificate operation failed. Install certificate operation failed. Assign certificate operation failed. Get certificate operation failed. Generate certificate operation failed. Set certificate name operation failed. Set certificate properties operation failed.

1396

Error Codes

UI Operations
In this section:
Visibility Customization Error ............................................................................. 1396 Create Custom Button Error .............................................................................. 1396 Get Custom Button Error ................................................................................... 1396 Delete Custom Button Error .............................................................................. 1396

Visibility Customization Error


Range: 9001
ERROR NUMBER 9001 DESCRIPTION General error while customizing visibility settings.

Create Custom Button Error


Range: 9101
ERROR NUMBER 9101 DESCRIPTION Failed to create custom button.

Get Custom Button Error


Range: 9201
ERROR NUMBER 9201 DESCRIPTION General error while getting information about the custom button.

Delete Custom Button Error


Range: 9301
ERROR NUMBER 9301 DESCRIPTION Failed to delete custom button.

Error Codes

1397

Upload Operations
In this section:
Upload Errors .................................................................................................... 1397

Upload Errors
Range: 10001 10100
ERROR NUMBER 10001 10002 10003 10004 10006 DESCRIPTION The uploaded file exceeds the upload_max_filesize directive set in php.ini. The uploaded file exceeds the MAX_FILE_SIZE directive specified in the HTML form. File uploaded not in full. No file uploaded. Temporary folder missing.

Secret Key Operations


In this section:
Secret Key Management Errors ........................................................................ 1397

Secret Key Management Errors


Range: 11001 11100
ERROR NUMBER 11001 11002 11003 DESCRIPTION Parsing error: wrong format of XML request. Create key operation failed. Secret key validation failed.

1398

Error Codes

Spam Filter Operations


In this section:
Spam Filter Management Errors........................................................................ 1398

Spam Filter Management Errors


Range: 12001 12100
ERROR NUMBER 12001 12002 12003 12004 12005 12006 DESCRIPTION Spam filter initialization failed. Failed to fetch info about spam filter. Argument is missing. Failed to update spam filter. Spam filter component not installed. Failed to update patter list.

Domain Alias Operations


In this section:
Domain Alias Management Errors ..................................................................... 1398

Domain Alias Management Errors


Range: 13001 13100
ERROR NUMBER 13001 13002 13003 13004 13005 DESCRIPTION Failed to create domain alias. Failed to delete domain alias. Failed to rename domain alias. Domain alias not found. Failed to configure domain alias settings.

Error Codes

1399

Database Server Operations


In this section:
Database Server Management Errors ............................................................... 1399

Database Server Management Errors


Range: 14001 14100
ERROR NUMBER 14001 14002 14003 14004 14005 14006 14007 14008 DESCRIPTION Failed to create database server. Failed to update database server. Failed to remove database server. Failed to get info about database server. Failed to set database server as default. Failed to get info about default database server. Failed to get info about local database server. Wrong database server type.

Migration Operations
In this section:
Migration Errors................................................................................................. 1399

Migration Errors
Range: 15000 15100
ERROR NUMBER 15000 15001 15003 15004 15005 15006 DESCRIPTION Internal migration error. Migration API not supported by the source server. Error while connecting to remote host. Domain number limit will be exceeded during migration. Account number limit will be exceeded during migration. Domain already exists on the destination server, or domain name is invalid

1400

Error Codes

15007 15008 15009 15010 15011 15012

IP does not exist on destination host. IP is missing in the target client IP pool. IP type is different from the server IP type. Domain exists on IP with different address or type. The target client does not exist on the destination server Client with this login name already exists on destination server, or login name is incorrect.

You might also like