Note: The number and location of these icons and links in your panel depend on the number of available services, installed applications, and functions provided in accordance with your software license. For this reason, some of the functions and items described in this guide might not be available to you. If you want to use the functions that are currently missing in your Panel, then upgrade your software license, install the necessary software packages, or contact your hosting service provider for assistance. Above the tabs, the following links are located:
Link with your name. Click this to specify your contact information, e-mail address, and set a new password for accessing the Panel. Log out. This closes your session when you have finished working with the Panel. Help. View the context-sensitive help articles. There is no dedicated Power User Panel guide; however, when you click this link, the relevant help topics will be shown either from Administrators Guide or Control Panel Users Guide.

CHAPTER 3

To change your password:
1. Click the Change Password link in the navigation pane. 2. Enter your old and new passwords. 3. Click OK.
To update your contact information:
1. Click the Profile & Preferences link in the navigation pane. 2. Update your information as required, and click OK.
If you forgot your password:
1. In your web browsers address bar, type the URL where your Parallels Plesk Panel is located. 2. For example, https://your-server.com:8443. 3. Press ENTER. Parallels Plesk Panel login screen will open. 4. Click the Forgot your password? link. 5. You will be prompted to specify your login name and e-mail address registered in the system. Type your login name into the Login box, type your e-mail address registered in the system into the E-mail box, and click OK. 6. If your password cannot be sent by e-mail because it was stored by the system in encrypted form, you will be prompted to set up a new password using a secret code that will be generated for that purpose and sent to your e-mail. 7. Once you received the e-mail from the password reminder, click the link in the message body. A new browser window will open. 8. At this step, specify your login name and a new password.

Overselling policy

Defines whether a reseller can sell more resources than allocated to them with the plan. If overselling is allowed, a reseller is governed by actual resource usage instead of initial resource allocation. Overselling is a marketing strategy based on the following scheme: a reseller, who was allotted, for example, ten gigabytes of disk space, allocates five gigabytes of disk space for each of their customers, assuming that none of them will actually use all of their allocated disk space.

Customers

Defines the total number of customer accounts that a reseller can create.

Other Resources

Note: Other resources have the same meaning as the ones defined in the hosting plans and subscriptions (on page 29). The only difference is that a reseller does not use the provided resources directly, but redistributes them by means of service subscriptions they create for their customers or for hosting their own websites.
Reseller-specific privileges (the ones that do not affect service subscriptions they create for their customers) are as follows:
Ability to use remote API
Defines if a reseller can remotely manage websites through custom applications. The remote API is an interface that can be used for developing custom applications integrated with websites, which could be used, for instance, for automating setup of hosting accounts and provisioning of services for customers purchasing hosting services from your site. To learn more, refer to the Parallels Plesk Panel API documentation available at the PTN portal (http://www.parallels.com/ptn/documentation/ppp/).

Access to the Panel

Defines if a reseller can use the Panel graphical user interface.
Customer account creation
Defines if a reseller can create user accounts and subscriptions for their customers in the Panel.

Allow overselling

Defines if a reseller can set up overselling policy, meaning that a reseller can themselves define if overselling is allowed to them or not.

Other Permissions

Note: Meanings of the other permissions are the same as in the service subscriptions (on page 33).

If you installed the Customer and Business Manager component and configured it to work with your Panel, then the following additional links are available in the Panel: Business Manager. Billing Details. Upgrade. Downgrade. Add-ons
Use these links for managing subscriptions in Business Manager. To learn about available operations, refer to the chapter Using Integrated Customer and Business Manager (on page 64).
To change a subscriptions hosting settings:
1. Go to Subscriptions, and click the <Subscription> in the list. 2. Click Change Hosting Settings. 3. Update the information, and click OK.
To transfer a subscription to another user:
1. Go to Subscriptions, and click the <Subscription> in the list. 2. Click Change Subscriber. 3. Select a new subscriber and click Next >>. 4. Review the information about the changes to be made to the subscription settings and click OK.
To transfer several subscriptions to another user:
1. Go to Subscriptions. 2. Select the subscriptions you want to reassign. 3. Click Change Subscriber. 4. Select a new subscriber and click Next >>. 5. Review the information about the changes to be made to the subscription settings and click OK.
To suspend a subscription:
1. Go to Subscriptions, and click the <Subscription Name> in the list. 2. Click Suspend.
To suspend several subscriptions at once:
1. Go to Subscriptions. 2. (Optional) Filter out active subscriptions: a. Click the button next to the search field above the list.
b. Under the Status filter, select Active. 3. Select target subscriptions in the list. 4. Click Suspend.
To activate a subscription:
1. Go to Subscriptions, and click the <Subscription Name> in the list. 2. Click Activate.
Note: Activating a subscription in this way is good only for the subscriptions that were suspended manually. If you activate in such a way an expired subscription, it will be automatically suspended on the next day. In such cases, renew subscriptions as described below.
To activate several subscriptions at once:
1. Go to Subscriptions. 2. (Optional) Filter out suspended subscriptions: a. Click the button next to the search field above the list.
b. Under the Status filter, select Suspended. 3. Select target subscriptions in the list. 4. Click Activate.
Note: Activating subscriptions in this way is good only for the subscriptions that were suspended manually. If you activate in such a way expired subscriptions, they will be automatically suspended on the next day. In such cases, renew subscriptions as described below.
To renew an expired subscription:
1. Go to Subscriptions, and click the <Subscription Name> in the list. 2. Click Activate. 3. Click Customize. 4. On the Resources tab, set up a new expiration date, or select Unlimited. 5. Click Update & Lock. 6. Click Unlock & Sync.

Adding and Removing IP Addresses
After installation, the Panel reads all your IP addresses from the network configuration files and can then use these IP addresses for hosting websites. When you obtain a new IP address that you would like to use on the server, you should add the address through the control panel, as the Panel might not recognize manual modifications you make to the network configuration files. With the Panel, you can mark all your IP addresses as shared or dedicated before you assign them to your customers. This allows the control panel to distinguish between them and not to let you assign a dedicated IP address to several customers at once. A dedicated IP address can be assigned to a single customer, while a shared IP address can be shared among several user accounts. Note that SSL protection with authentic digital certificates and Anonymous FTP services are available only to dedicated hosting accounts on a dedicated IP address. Shared hosting accounts can also have SSL protection, but visitors to such protected sites will get error messages in their browsers.
To view the IP addresses you have at your disposal:
1. Go to Tools & Utilities > IP Addresses (in the Resources group).
Your IP addresses are listed and the following supplementary information is given: An icon in the S (Status) column shows if your IP address is properly configured on the network interface. If your IP address was removed from the network interface, an icon will show. An icon in the T (Type) column shows if an address was allocated to a single customer as a dedicated IP address, and if an address is shared among many customers. The IP address, Subnet Mask and Interface columns show which IP addresses are on which network interfaces. The Resellers column shows the number of user accounts who you assigned a given IP address. To view the users by names, click the respective number in the Resellers column. The Domains column shows a number of websites hosted on an IP address. To view the domain names of these websites, click the respective number in the Domains column.
2. To update the list of IP addresses and their status, click Reread IP.
To add a new IP address to the server:
1. Go to Tools & Utilities > IP Addresses (in the Resources group), and click Add IP Address.
2. Select the network interface for the new IP from the Interface menu. All network cards installed on your server are shown in this menu. 3. Enter the IP address and subnet mask in the corresponding box (e.g., 123.123.123.123/16). 4. Select the type of the new IP address, shared or exclusive. 5. From the drop-down box, select the SSL certificate for the new IP address. You can select the following certificates:
Default certificate - the certificate that comes with the Parallels Plesk Panel distribution package. However, this certificate is not recognized by web browsers as it is not signed by a Certificate Authority (a warning message appears). The default certificate is used to provide access to the control panel via the https protocol (https://server-name-or-IP-address:8443/). Other certificates - the certificates (self-signed or signed by a Certificate Authority) that you added to the repository of SSL certificates (about adding certificates, see the section Securing Sites with SSL encryption).

6. If your server is running Windows operating system, select the FTP over SSL checkbox if you want to enable the ability to use secure FTP connection (FTP over SSL) for the domain on an exclusive IP address.
Note: To enable secure FTP connections, the FTP server installed on your Parallels Plesk Panel server must support FTP over SSL. Currently, only Gene6 and Serv-U FTP servers support FTP over SSL.

7. Click OK.

To remove an IP address from the server:
1. Go to Tools & Utilities > IP Addresses (in the Resources group). 2. Select the respective checkbox and click Remove, confirm removal and click OK.
To assign an IP address to a reseller:
1. Go to Tools & Utilities > IP Addresses (in the Resources group), and click the corresponding number in the Resellers column, then click Assign. 2. Select the user account you need and click OK.
To revoke an IP address from a user:
1. Go to Tools & Utilities > IP Addresses (in the Resources group), and click the corresponding number in the Resellers column. 2. Select the respective checkbox and click Remove. 3. Confirm removal and click OK.
Since users can refer to a web resource on your server by typing an IP address and there can be several websites hosted on that address, the Panel needs to know which of the sites to show in such cases. The Panel automatically assigns the first website created on an IP address as the default website; however, you can select any other website and make it default.
To assign a default website (default domain) for an IP address:
1. Go to Tools & Utilities > IP Addresses (in the Resources group), and click the IP address you need. 2. In the Default site menu, select the site you need and click OK.
To change an IP address allocation type (shared, exclusive) or assign another SSL certificate to an IP address:
1. Go to Tools & Utilities > IP Addresses (in the Resources group), and click the IP address you need. 2. Select the required IP address allocation type and SSL certificate, and click OK.
Viewing and Selecting Software Components Used on the Server
Parallels Plesk Panel supports a variety of third-party software components, from antivirus solutions to webmail servers. If you are using Windows-based hosting, then you can select the components that should be used on your server.
To see the list of available components and to select the software components that should be used by Parallels Plesk Panel:
1. Go to Settings > Server Components (in the General group).
All installed components are listed. If you are using Windows-based hosting, then you can see the current state of components and select which components should be used. The current state of a component is marked by an icon: means that the Panel is using this component, and the component is working. means that the Panel is not using this component (usually because a license key has expired or missing), but the component is working. means that the Panel is not using this component, because the component is stopped. means that the Panel is not using this component, but the component is installed in the system and available.

1. Go to Settings > Firewall (in the Security group). 2. Click the network interface you need.
All currently defined rules are listed. The S (status) column shows the icon if the firewall blocks the packets that match the rule, and the icon if the firewall allows the packets that match the rule to pass through. Note: Configuring firewall for specific network interfaces is only available under Microsoft Windows Server 2003. If you are using Microsoft Windows Server 2008, go to the Firewall Rules tab.
3. Do any of the following:
To view or change the properties of a rule, click the respective rules name. To save any changes you have made to the rule, click OK. To return to the previous screen without saving any changes, click Cancel or click Up Level. To allow connections to a service, click Add Firewall Rule, specify the rule name for future reference, specify the port and the protocol for which incoming connections must be allowed. Leave the Switch on rule checkbox selected, if you wish to apply the rule immediately. Click OK. To allow connections to a service that you previously made inaccessible, click the respective icon in the S column. To temporarily block connections to a service, click the respective S column. icon in the
To permanently block connections to a service, select the checkbox corresponding to the rule that allows connections to the respective service, and click Remove. Removing a rule blocks the connections that were specified in that rule.
Allowing and Blocking Inbound Connections
To allow inbound connections to a service:
Note: Configuring firewall for specific network interfaces is only available under Microsoft Windows Server 2003. If you are using Microsoft Windows Server 2008, go to the Firewall Rules tab.
3. Click Add Firewall Rule, and specify the following properties:
The rule name for future reference The port or port range and the protocol for which inbound connections must be allowed
4. Leave the Switch on rule checkbox selected, if you wish to apply the rule immediately. 5. Click OK.
To block the previously allowed inbound connections to a service:
3. Select the checkbox corresponding to the rule that allows connections to the respective service, and click Remove.
Removing a rule blocks the connections that were specified in that rule.
Allowing and Blocking ICMP Communications
ICMP communications are used for network troubleshooting purposes. By default, all ICMP communications are allowed. For the detailed description of ICMP messages, please refer to: http://msdn.microsoft.com/library/default.asp?url=/library/enus/xpehelp/html/xeconconfiguringicmpsettingsinwindowsfirewall.asp

Greylisting (available only for Linux hosting). Greylisting is a spam protection system which works as follows: For every e-mail message that comes to the server, senders and receivers e-mail addresses are recorded in a database. When a message comes for the first time, its sender and receiver addresses are not listed in the database yet, and the server temporarily rejects the message with an SMTP error code. If the mail is legitimate and the sending server is properly configured, it will try sending e-mail again and the message will be accepted. If the message is sent by a spammer, then mail sending will not be retried: spammers usually send mail in bulk to thousands of recipients and do not bother with resending. The greylisting protection system also takes into account the server-wide and peruser black and white lists of e-mail senders: e-mail from the white-listed senders is accepted without passing through the greylisting check, and mail from the blacklisted senders is always rejected. When the greylisting support components are installed on the server, then greylisting is automatically switched on for all domains. You can switch off and on greylisting protection for all domains at once (at Settings > Spam Filter Settings), or for individual subscriptions (in Control Panel > Mail tab > Change Settings).
Setting Up SpamAssassin Spam Filter...110 Setting Up Spam Protection Based on DomainKeys (Linux Hosting)..112 Switching On Spam Protection Based on DNS Blackhole Lists.114 Setting Up Server-wide Black and White Lists...114 Setting Up Support for Sender Policy Framework System (Linux Hosting).115 Setting Up Spam Protection Based on Greylisting (Linux Hosting).116
Setting Up SpamAssassin Spam Filter
To switch on SpamAssassin spam filter:
1. Go to Settings > Spam Filter Settings (in the Mail group). 2. To allow server wide filtering based on the settings you define, select the Switch on server-wide SpamAssassin spam filtering checkbox. 3. To let your users set their own spam filtering preferences on a permailbox basis, select the Apply individual settings to spam filtering checkbox. 4. If you wish to adjust the amount of system resources the spam filter should use (available only for Linux hosting), type the desired value from 1 to 5 into the Maximum number of worker spamd processes to run (1-5) box (1 is the lowest load, and 5 is the highest). We recommend that you use the default value. 5. If you wish to adjust the spam filters sensitivity, type the desired value in the The number of points a message must score to be considered spam box.

Preventing Your Customers From Sending Mass E-mail (Linux Hosting)
To prevent your users from sending mass e-mail, do the following:
1. Create a file named maxrcpt in the directory $QMAIL_ROOT_D/qmail/control/
where $QMAIL_ROOT_D is the location defined in the file /etc/psa/psa.conf file.
2. Type the number of allowed recipients in this file and save it.
Note that this number also affect sending of messages to mailing list or mail group subscribers. That is, if you set the value to 100, then only 100 subscribers will receive the message sent to a mailing list or a mail group. When you no longer need to restrict the number of recipients, delete the maxrcpt file.
Configuring Parallels Plesk Panel to Use SiteBuilder in Trial Mode
You can allow your customers to use SiteBuilder in trial mode. Trial mode gives customers the ability to create websites in SiteBuilder with all available functionality. However, publishing of trial websites is not available to customers until they pay for these websites by purchasing a service plan add-on or signing up for your hosting services. Trial mode can be granted to your existing customers through a Hosting Plan, and it can be provided for potential customers who visit your website.
To configure Parallels Plesk Panel to use SiteBuilder in trial mode:
1. Go to Settings > SiteBuilder Settings (in the Applications & Databases group). 2. Specify Trial website lifetime. This is how much time should pass before those trial websites that were not purchased by customers are removed from the server. 3. To attract new customers by advertising hosting with SiteBuilder and providing SiteBuilder demo to them, select the Enable public access to trial mode checkbox. Below you will find the Trial mode access URL. This URL will open SiteBuilder in trial mode. Publish this URL on your website to advertise hosting with SiteBuilder and attract customers. 4. To display additional notification about SiteBuilder working in trial mode, select the Display trial mode notification in SiteBuilder editor checkbox. Trial mode notifications in SiteBuilder editor can be customized. 5. Click OK.

Setting Up Remote Database Hosting... 126 Managing Database Servers.... 128
Setting Up Remote Database Hosting
After you have set up the required remote database server, you need to register this database server in the Panel.
To register a database server with the Panel:
1. Log in to Parallels Plesk Panel. 2. Go to Tools & Utilities > Database Servers, and click Add Database Server. 3. Specify the properties of the database server:
Specify database server engine in the Database server type menu. Specify hostname or IP address of the database server. Specify the port number the database server is listening on. This option is available only for MySQL. By default, MySQL servers listen on port 3306. You can leave the Port number box blank, if your MySQL database server is listening on the default port. Note: Do not enter the value for MySQL server port equal to 8306, because it is used by Parallels Plesk Panel for communication with its internal database. Specify which database type is running on the database server. To make this database server default for hosting customers databases, select the Use this server as default for MySQL checkbox. If you have a MS SQL database server, select the checkbox Use this server as default for MS SQL labeled. Specify the database server administrators login name and password.
To set up database hosting preferences that will affect all databases created through Parallels Plesk Panel:
1. Go to Settings > Database Hosting Preferences (in the Databases group). 2. To simplify maintenance of customers databases, select the Add users login name and underscore to beginning of database names checkbox. All names of newly created databases will look like username_database name. This will allow you to locate databases related to a particular Parallels Plesk Panel user. Note that even if you do not select this checkbox, on creation of a new database, Parallels Plesk Panel will add a username to the database name input box, and you will be able to edit it or remove it.
3. You can also set up the Panel to add usernames to corresponding database user names, further simplifying the maintenance of customers databases. To do so, select the Add users login name and underscore to the beginning of database user names checkbox. All names of newly created database users will look like username_database user name. This will allow you to locate database users related to a particular Parallels Plesk Panel user. 4. Specify whether creation of databases is allowed on your Parallels Plesk Panel server. Some applications do not support remote databases and can work only with databases hosted on the same server. We recommend leaving the default option Allow local hosting of databases for these web applications selected, otherwise, you will not be able to use such applications. 5. Click OK.

Note: Parallels Plesk Panel supports separate configurations for different versions of the.NET framework (1.1.x and 2.0.x).
Configuring IIS Application Pool (Windows Hosting)
IIS application pool serves websites and web applications hosted on your server. Dedicated IIS application pool allows your customers to have a level of isolation between websites. Since each dedicated application pool runs independently, errors in one application pool belonging to one user will not affect the applications running in other application pools dedicated to other users. By default, Parallels Plesk Panel offers a shared application pool for all users. However, users can use dedicated application pools if this option is provided by the hosting package. IIS application pool can work in the following two modes: Shared pool - one pool is used for all users and websites by default. Dedicated pool - separate pool for every customer is provided. It is also possible to allocate per-package pools within the customers pool, that will isolate running websites hosted under a particular package from other customers websites.
To change the IIS application pool working mode:
1. Go to Tools & Utilities > IIS Application Pool. 2. Select the Global Settings tab. 3. Select the required mode and click OK.
To limit the amount of CPU resources that the IIS application pool can use:
1. Go to Tools & Utilities > IIS Application Pool. 2. Select the Switch on CPU monitoring checkbox and provide a number (in percents) in the Maximum CPU use (%) field. 3. Click OK.
To stop all applications running in the server application pool:
1. Go to Tools & Utilities > IIS Application Pool. 2. Click Stop.
To start all applications in the application pool:
1. Go to Tools & Utilities > IIS Application Pool. 2. Click Start.
To restart all applications running in the application pool:
1. Go to Tools & Utilities > IIS Application Pool. 2. Click Recycle. This can be handy if some applications are known to have memory leaks or become unstable after working for a long time.

Configuring Shared SSL (Windows Hosting)
Shared SSL is a means of securing access to a site with SSL (Secure Sockets Layer) for site owners without having them purchase their own SSL certificate. Websites that employ shared SSL are, in fact, using the certificate shared by another domain. The domain that shares its SSL certificate with others is called master SSL domain. You can pick any website that belongs to you, switch on SSL support in web hosting settings, install a valid SSL certificate on that site, and make it act as a master SSL domain for all other websites hosted on the server. Or you can pick a website that belongs to one of your users (reseller or customer account), switch on SSL support in web hosting settings, install a valid SSL certificate on that site, and make it act as a master SSL domain for all websites of this user. Once the master SSL domain is assigned, you or your customers need to add shared SSL links for each website that needs secure access.
To configure the master SSL domain and enable shared SSL on your server:
1. Go to Tools & Utilities > Shared SSL (in the Resources group). 2. Select the Switch on shared SSL checkbox. 3. Select the required website from the Domain name menu. Only websites that are hosted on your server and have SSL enabled are present in the list. 4. Click OK.
For information about adding shared SSL links for websites, refer to the Control Panel Users Guide, section Using SSL Certificate Shared by Another Website.
To disable shared SSL on your server:
1. Go to Tools & Utilities > Shared SSL (in the Resources group). 2. Clear the Switch on shared SSL checkbox. 3. Click OK.

Configuring Statistics

After installation, Parallels Plesk Panels statistics utility is set up to: Count the inbound and outbound traffic. Count the disk space occupied by web content, log files, databases, mailboxes, web applications, mailing list archives, and backup files. Keep the web statistics and traffic statistics gathered by Webalizer or AWstats programs only for the last three months.
To review or adjust these settings:
1. Go to Settings > Settings of Server Statistics (in the General group). 2. Under the System preferences group, specify the term during which the bandwidth usage statistics should be kept for your customers. 3. Specify the items that should be considered when disk space and bandwidth usage is calculated. 4. Click OK.
Note: In addition to the settings related to statistics, this screen provides the means to rename your servers hostname, and the option to allow or forbid users to create new subdomains and domain aliases in the DNS zones belonging to other users (the Do not let users create DNS subzones in other users DNS superzones checkbox). We recommend that you select this checkbox, otherwise, users will be able to create subdomains under domains belonging to other users, and set up websites and e-mail accounts which could be used for spamming or even phishing or identity theft. For instruction on viewing statistics, refer to the chapter Viewing Statistics.

5. Select the type of operating system running on the source host. This option is available if you are using Parallels Plesk Panel for Windows hosting platform. 6. Specify the path to the directory where temporary files will be stored. 7. Specify whether you want to transfer all data related to user accounts and sites from the source server, or only specific items.
8. If your source and destination servers are Linux-based, select the rsync transport option to preserve disk space on the source and target servers during migration.
This is extremely important in case you do not have much spare disk space on either server.
9. Click Next>>. The migration manager will connect to the specified server and gather information about the business objects of the source hosting platform. 10. If you are transferring data from hosting platforms other than Parallels Plesk Panel, select the version of the migration agent that must be used and then click Next >>. Parallels Plesk Panel automatically selects the appropriate agent version; however, if data transfer fails, you can try selecting another version of migration agent. 11. If you have chosen to transfer only specific items, at this step, select the checkboxes corresponding to the user accounts and websites that you want to transfer. Also, specify what types of data should be transferred:
All settings and content. All settings and content except mail. Only mail accounts with e-mail messages.
12. Click Next >>. 13. Once the data are retrieved from the source server, specify the new IP addresses that should be used. If you have a great number of IP addresses, at this step, you can download the current IP mapping file, correct it in a text editor or by running a custom find and replace script, and then upload it back to the server. 14. Click Next >>. The data transfer process should start immediately; however, If some of the selected items cannot be transferred because of possible configuration or resource usage conflicts, you will be taken to the next step and prompted to specify the conflict resolution policies. 15. If prompted, specify how to resolve the following types of conflicts:
a Timing conflicts that occur when an item to be transferred already exists on the destination server and has a more recent modification date. You can choose any of the following options: Use the configuration and data from the source server. This will overwrite the configuration and data currently present in the destination server with the configuration and data retrieved from the source server. Use the configuration from the destination server, and the data from the source server. Do not transfer items with timing conflicts.
Resource usage conflicts that occur when an item to be transferred would exceed the resource usage limits defined on the destination server for this type of items. You can choose any of the following options:

For example, C:\temp.

4. Click Next >>.
If the xml file with information about business objects of the source host is found in the specified directory, then the data import starts.

CHAPTER 10

The Panel checks for updates every night. If updates are available, the Panel automatically downloads and installs them. This is the default setting: At Settings > Server Settings, the Automatically download and install updates checkbox is selected. If a new version of the Panel is available, the Upgrade now link is shown at the top of the screen on the Home page. If you do not want the Panel to automatically download and install updates, go to Settings > Server Settings, and clear the Automatically download and install updates checkbox. After that, if updates are available, an alert will be shown at the top of the screen on the Home page, and the following links will be presented: View detailed information about the update. Click this if you want to view the information about the update before installing it. Update now or Upgrade now. The Update now link is shown if updates are available for your product version. In case an upgrade to a newer version is available, then the Upgrade now link is shown. Click the link corresponding to the operation you want to perform. If you choose to install updates, then all required software updates and packages will be installed. If upgrading to a new version, you will be prompted to select the product versions and components that you want to install. In case of failure, the panel will show a link to a log file that contains all the information required for troubleshooting. If you experience problems with updating or upgrading your software, contact the Parallels support department, and send them this log file. Update later. Click this link if you do not want to install any updates at the moment. The alert text and the links will no longer be shown in the Panel; they will appear again the next time a new update is available.
In addition to using these links, you can update or upgrade the Panel using the following steps:
1. In your Panel, go to Tools & Utilities > Updates (in the Panel group). A new browser window or tab will open. 2. In this window, select a checkbox corresponding to the update (or a new Panel version) that you want to install and click Continue. 3. When updating is finished, click OK.
Notes on updating procedures:
When upgrading to a new control panel version, you will be notified by e-mail of upgrade procedure start and end. The notification message will include the event log and a list of installed packages, if upgrade is successful. However, you may not receive any error notice if your mail server fails. In this case you can check for errors in the autoinstaller.log file located in the /tmp directory on the server hard drive. All control panel operations are suspended during installation of the so-called base packages that affect the control panels core functionality. If you need to install a new license key after upgrade, refer to the section Upgrading Your License Key (on page 72). If you experience any problems with installing a license key, please contact Parallels technical support: http://www.parallels.com/contact/.

Parallels Plesk Panel

Copyright Notice
Parallels Holdings, Ltd. c/o Parallels International GMbH Vordergasse 49 CH8200 Schaffhausen Switzerland Phone: +411 Fax: +2010 Copyright 1999-2011 Parallels Holdings, Ltd. and its affiliates. All rights reserved. This product is protected by United States and international copyright laws. The products underlying technology, patents, and trademarks are listed at http://www.parallels.com/trademarks. Microsoft, Windows, Windows Server, Windows NT, Windows Vista, and MS-DOS are registered trademarks of Microsoft Corporation. Linux is a registered trademark of Linus Torvalds. Mac is a registered trademark of Apple, Inc. All other marks and names mentioned herein may be trademarks of their respective owners.

Contents

Preface 4
About This Guide..... 4 Who Should Read This Guide... 5 Prerequisites for This Document.... 5 Typographical Conventions.... 5 Feedback..... 6

Plesk API RPC Protocol

Client-Server Model.... 9 API RPC Packets.... 9 Packet Structure.... 10 Packet Sample.... 11 Validation Schemas.... 14 Descriptors Overview.... 18 GUIDs Overview.... 19

Creating Client Software

Client Application Structure.... 21 Creating Plesk API RPC Packet... 22 Sending Request Message Via Plesk API RPC... 23 Parsing Response Message Received From Plesk... 25 Handling Errors.... 28 Client Code Samples.... 29 PHP Client Application.... 30 C# Client Application.... 35 VB.NET Client Application... 41

Preface

In this section:
About This Guide.... 4 Who Should Read This Guide... 5 Prerequisites for This Document... 5 Typographical Conventions... 5 Feedback.... 6

About This Guide

This part of Plesk API RPC documentation includes the protocol overview and samples of tools used to interact with Plesk server via the protocol. Chapter Plesk API RPC Protocol (on page 7) states the concepts of Plesk API RPC technology. It explains what Plesk API RPC protocol is, why it is necessary, how Plesk XML API can be used for the interaction between Plesk and third-party software, and the main interaction principles as well. Chapter Creating Client Software (see page 20) touches upon the programming issues, it is meant to explain what kind of software should be created, what steps should be implemented to serve the data turnaround, and so on. Each step is considered in detail using code samples where necessary.
Who Should Read This Guide
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. 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

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

To support interaction between Plesk and third-party software, Plesk provides XMLbased API. This interface exposes a set of functions for managing Plesk logical objects. The Plesk API RPC protocol was designed as a means of calling to these API functions remotely. This is the XML-over-HTTP protocol that exchanges data in the form of specifically formatted packets. Who can use Plesk API RPC protocol At the moment, the use of Plesk API RPC protocol is allowed to Plesk Administrator, Plesk resellers and Plesk clients (the list of API RPC users tends to be enlarged). These users are provided with programmatic means of managing various Plesk objects they own. Plesk Administrator is allowed to perform all operations of whatever version of the API RPC protocol they use. Plesk clients/resellers have access to a limited number of operations within each particular version of API RPC. When using a Plesk client/reseller account, a strict requirement is that options 'CP access' and 'Ability to use remote XML interface' are enabled, of which Plesk Administrator should be requested in advance.
Note: There are no API RPC versions designed specifically for Plesk for Linux/Unix or Plesk for Windows. Both products share the same versions of Plesk API RPC protocol. What versions of Plesk API RPC protocol are in use Plesk API RPC protocol evolves in sync with Plesk constantly: When new features appear in Plesk, they are implemented in the protocol. Here are the versions of Plesk API RPC protocol recommended for use with the later versions of Plesk:

Beginning of the XML part Packet header The version attribute specifies the required version of Plesk API RPC protocol.
<client> <add> <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>steve78</passwd> <status>0</status> <phone>9944</phone> <fax>3905</fax> <email>host@logicsoft.net</em ail> <address>105 Brisbane Road, Unit 2 </address> <city>Toronto</city> <state/> <pcode/>
Packet body Always starts from tag of the related operator. This particular packet uses the client operator to create a Plesk client account. The elements nested within the gen_info node contain data necessary to register the new client in Plesk database. The elements nested within the limits node specify the clients restrictions imposed on use of various Plesk resources. The elements nested within the permissions node indicate the state (enabled/disabled) of various management capabilities for the new client. E.g., the remote_access_interface node nested within permissions indicates that the client is allowed to access Plesk object via Plesk API RPC.
<country>CA</country> </gen_info> </add> </client> </packet>
The structure of the packet body is compliant with the client_input.xsd XML schema of Plesk XML API v.1.4.0.0.
Trailing tag closing the packet
The example above shows the request message structure. Both types are similar in the structure, but HTTP headers and bodies look different. Message sent by the server in response to the request above could look as follows: HTTP/1.OK Connection: close Content-Length: 161 Content-Type: text/xml Date: Mon, 3 Jul 2006 10:55:08 GMT Server: Plesk/800 <?xml version=1.0 encoding=UTF-8 standalone=no?> <packet version=1.4.0.0> <client> <add> <result> <status>ok</status> <id>5361</id> </result> </add> </client> The structure of the packet body is compliant with the client_output.xsd XML schema of Plesk XML API v.1.4.0.0. Trailing tag closing the packet The nested lines indicate that the ADD operation was successfully performed. Also, the server passes back the clients ID. Standard header of a valid XML document XML packet header Packet body The root node of the packet body is the client operator. Standard header of the HTTP server response The MIME type is text/xml. The Server element shows that the request was handled by Plesk v.8.0.0 on the server side.

</packet>

Validation Schemas
XML schema are used in the following two cases: 1. When a packet is created (request packet created by developer/client software, or response packet created by Plesk API RPC server) 2. When a packet is read and validated (request packet validated by Plesk server, or response packet validated by a client software)
Creating XML-RPC packets First, let us look at how to retrieve the useful information from the XML schema when creating a packet. Assume that we have Plesk Client access permissions, and need to create a domain and remove some old ones. Assume that we know the version of Plesk installed on the server side, say, it is Plesk 8.0 for Linux/Unix. All this means that we better use version 1.4.1.0 of API RPC. The operations on domains for this version are described in the relevant domain_input.xsd schema. Its graphical representation (a cut version) correlates with the body of the XML packet as follows:
Figure 3: XML schema XML packet body looks as follows:
<domain> <add> <gen_setup> <name>newdomain.com</name> <ip_address>123.123.123.123</ip_address> </gen_setup> </add> <del> <filter> <id>1</id> <id>2</id> <id>3</id> </filter> </del> </domain>
Here, the requested domain operations (ADD and DEL) are nested within the DOMAIN operator element. Similarly, operations on Plesk clients would require the use of the CLIENT operator, and so on. For information on which operators supported by each API RPC version, refer to the API RPC Versions section of the API RPC Reference. Note that starting with version 1.4.0.0, Plesk API RPC supports heterogeneous requests, i.e., the requests for operations on different Plesk objects. Such a request can look as follows:
<client> <add> </add> </client> <domain> <add> </add> </domain>
Each group of operations is isolated within the relevant operator so that operations with similar names requested for different Plesk objects would never conflict. Validating XML-RPC packets Let us look at how Plesk API RPC server chooses the right XML schema(s) to validate a packet just arrived.
Figure 4: The structure of Plesk API RPC server Plesk API RPC server is arranged as a set of agents - or operators - managed by the Agent Engine. Every agent is a logical block responsible for handling a certain group of commands, and the Agent Engine serves as a packet dispatcher. In addition, Agent Engine is associated with several sets of XML API schemas. Each set relates to a certain API RPC version supported by Plesk. An entry point to each version is the agent_input.xsd file that references all input schemas of the same version.

Plesk API RPC server functions as follows. First the pure XML packet, its HTTP header peeled off, gets to Agent Engine. Agent Engine retrieves the required API RPC version from the packet header and decides which of two supported schema resolution models to apply. Old schema resolution model The old schema resolution algorithm is applied to incoming packets that specify API RPC version 1.3.5.1 and lower. This algorithm does not implement the validation as it is. Once Agent Engine has read the API RPC version form the packet header, the incoming packet is passed further to the relevant operator. The operator parses the packet body, forms calls to Plesk internal functions, performs these invocations, gets the result, forms the response API RPC packet, and returns it to Agent Engine.
Figure 5: Old schema resolution model New schema resolution model In Plesk 8 for Linux/Unix / Plesk 7.5.6 for Windows and higher, validation takes place before the incoming packet is passed to the proper operator. The Agent Engine retrieves the API RPC version from the packet header, chooses the matching set of XML schemas, and switches to the right agent_input.xsd schema. This schema validates the operator level of the packet, after which each operator section of the packet is validated with the proper subsequent schema.
Figure 6: New schema resolution model If the packet is considered invalid, Agent Engine forms an error report and sends it back to the client. If all elements of the packet are validated successfully, Agent Engine checks whether it has all agent modules necessary for further processing and invokes them one after another. Each agent (operator) invoked receives its operator packet section, parses it, forms calls to internal functions, and returns the result of the executed commands to Agent Engine.

Descriptors Overview

Starting with version 1.5.0.0, Plesk API RPC protocol supports descriptors - containers that store info on properties of Plesk business logic objects. There are two kinds of descriptors: object descriptors and property descriptors. Property descriptor is comprised of parameters that specify an object property. There can be only one property descriptor for each property. Every object descriptor is composed of a set of property descriptors and correlation between properties of the object.
Figure 7: Representation of object descriptor The basic goal of descriptors is to make object properties independent of a protocol version. Now to retrieve the properties, you can retrieve object descriptor that shows properties available for a current user in the current version of Plesk. This provides more flexible and convenient mechanism of adaptation third-party applications to changes in Plesk business model. All descriptors can be divided into the following three groups: Server-level descriptors Client-level/Reseller-level descriptors Domain-level descriptors

(HOST, 10.58.97.81); (PORT, 8443); (PATH, enterprise/control/agent.php); https://. HOST. :. PORT. /. PATH;
define define define $url =
The array of header elements as follows:
$headers = array( HTTP_AUTH_LOGIN: admin, HTTP_AUTH_PASSWD: setup, Content-Type: text/xml );
Then the CURL engine is initialized and set to use HTTPS, and all parameters required for the HTTP header are passed in to it:
// initialize the curl engine $ch = curl_init(); // set the curl options: // do not check the name of SSL certificate of the remote server curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); // do not check up the remote server certificate curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // pass in the header elements curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // pass in the url of the target server curl_setopt($ch, CURLOPT_URL, $url);
One more parameter required by the CURL engine is the Plesk API RPC packet. Assume that the packet is formed as follows:
$packet = <<<EOP <?xml version="1.0" encoding="UTF-8"?> <packet version="1.4.0.0"> <client> <add>
Creating Client Software <gen_info> <cname>LogicSoft Ltd.</cname> <pname>Stephen Lowell</pname> <login>stevelow</login> <passwd>steve78</passwd> <status>0</status> <phone>9944</phone> <fax>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>100000</disk_space> <max_dom>50</max_dom> <max_subdom>250</max_subdom> <max_webapps>30</max_webapps> <max_traffic>50000</max_traffic> <max_db>200</max_db> <mysql_dbase_space>50000</mysql_dbase_space> <max_shared_ssl_links>50</max_shared_ssl_links> <expiration>1134616208</expiration> </limits> <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> EOP;

Any of these check-ups can fail which makes further checkups and command execution impossible. Since the server side has got stuck at one of the preliminary checkup steps (i.e., it has not come to executing the requested operation yet), the response packet is formed with the following elements: system containing an error description; defined by type resultType in the common.xsd schema output, an optional element containing a message taken from stderr (if not empty) of the failed component; defined by type garbageOutput in the plesk_common.xsd schema
For example, the response received from Plesk API RPC server at the attempt to use a non-existing version of the API RPC protocol looks as follows:
<packet version="1.4.2.0"> <system> <status>error</status> <errcode>1005</errcode> <errtext>API RPC protocol version not supported.</errtext> </system>
Creating Client Software <output></output> </packet>
The list of error codes supported by Plesk API RPC server is presented in the Error Codes section of the Plesk API RPC Protocol Reference. Execution errors If all checkups have been passed through successfully, the selected agents try to execute the requested operations in series. If any operation fails, the related agent reports about the execution error. All reports are gathered by Agent Engine which forms a response packet based on the output XML schemas. E.g., if failed to create a domain, the domain operator will form an error response using the domain_output.xsd schema:
<packet version="1.4.2.0"> <domain> <add> <result> <status>error</status> <errcode>2300</errcode> <errtext>Failed to add domain.</errtext> </result> </add> </domain> </packet>
Note: Response packet can report about more than one execution error. This is possible if the incoming packet requests for more than one operation and some (or all) of them fail. Also, beginning from version 1.4.0.0 of API RPC, the response packet can contain multiple operator sections if the incoming packet requested for operations on multiple Plesk objects.

Client Code Samples

This section presents sample client applications in PHP, C# and VB.NET that illustrate how to utilize the API RPC protocol.
PHP Client Application... 30 C# Client Application.... 35 VB.NET Client Application... 41

PHP Client Application

The following code sample presents ready-to-use client application written in PHP. Note: If you want to use this sample make sure you have PHP 4.0.2 or later. For more information, visit http://php.net/manual/en/ref.dom.php or http://php.net/manual/en/ref.curl.php.
Comments class ApiRequestException function domainsInfoRequest() function curlInit() Extends the standard Exception class. Visit http://www.php.net/manual/en/language.exceptions.php for details. Uses the DOM model to compose a request XML packet. Returns the resulting DOM object. Initializes the CURL session with necessary options as follows: CURLOPT_URL specifies the destination URL
CURLOPT_RETURNTRANS set to true means that the FER resulting output will be returned from the server in the form of a string. CURLOPT_POST set to true means that the packet will be sent via HTTP POST.
CURLOPT_SSL_VERIFYPE set to false stops CURL ER from verifying the peer's certificate. CURLOPT_SSL_VERIFYHO set to false stops CURL ST from verifying the host. CURLOPT_HTTPHEADER specifies an array of HTTP header fields to set.
Returns the handler of the URL session.

function sendRequest()

Sends the HTTP packet by means of CURL and gets the pure XML response packet (without the HTTP header). Closes the CURL session and returns the resulting packet (a plain text with XML tags). To learn more about the CURL engine, visit http://www.php.net/manual/en/ref.curl.php. Gets the response packet (plain text) as a parameter. Parses the packet using SimpleXML and returns the SimpleXMLElement object in which the packet is structured as a tree. To learn more about the SimpleXML extension of PHP, visit http://www.php.net/manual/en/ref.simplexml.php. Gets the response packet of type SimpleXMLEelement and checks the result node. If this node holds 'error', then the function throws an exception with a string passed in the errtext node.

function parseResponse()

function checkResponse()
The main() function invokes these functions in the order they are considered. First it calls domainInfoRequest() to form a packet as follows:
<?xml version="1.0" encoding="UTF-8" ?> <packet version="1.6.2.0"> <domain> <get> <filter/> <dataset> <limits/> <prefs/> <user/> <hosting/> <stat/> <gen_info/> </dataset> </get> </domain> </packet>
Then curlInit() is called to initialize CURL session with options. The sendRequest function sends a packet with the HTTP header as follows:
POST /enterprise/control/agent.php HTTP/1.1 Host: 10.58.32.100:8443 HTTP_AUTH_LOGIN: login HTTP_AUTH_PASSWD: qwedsa HTTP_PRETTY_PRINT: TRUE Content-Length: 294 Content-Type: text/xml

Creating Client Software function parseResponse($response_string) { $xml = new SimpleXMLElement($response_string); if (!is_a($xml, 'SimpleXMLElement')) throw new ApiRequestException("Cannot parse server response: {$response_string}"); return $xml; } /** * Check data in API response * @return void * @throws ApiRequestException */ function checkResponse(SimpleXMLElement $response) { $resultNode = $response->domain->get->result; // check if request was successful if ('error' == (string)$resultNode->status) throw new ApiRequestException("The Panel API returned an error: ". (string)$resultNode->result->errtext); } // // int main() // $host = '10.58.32.100'; $login = 'admin'; $password = 'qwedsa'; $curl = curlInit($host, $login, $password); try { $response = sendRequest($curl, domainsInfoRequest()->saveXML()); $responseXml = parseResponse($response); checkResponse($responseXml); } catch (ApiRequestException $e) { echo $e; die(); } // Explore the result foreach ($responseXml->xpath('/packet/domain/get/result') as $resultNode) { echo "Domain id: ". (string)$resultNode->id. " "; echo (string)$resultNode->data->gen_info->name. " (". (string)$resultNode->data->gen_info->dns_ip_address. ")\n"; } ?>

C# Client Application

The following code sample presents ready-to-use client application written in C#. Comments Class Request implements sending a request packet to the Panel-managed server via HTTP and receiving the response packet. It has the following members:
public string Hostname Holds the host name (IP address) of the Panelmanaged server to which the request packet is sent. Is "localhost" by default. Holds the Panel administrator's login. Is "admin" by default. Holds the Panel administrator's password. Is "setup" by default. Holds the version of API RPC protocol used for interaction with the Panel. A handler used to receive schema validation errors. Holds the URL of the Panel Agent that will handle the request packet on the server side. Holds the URL of the validation schema that will be applied to the request packet before it is sent to the server side. Holds the URL of the validation schema that will be applied to the response packet after it is received on the client side. Gets the request packet (in the form of the XmlDocument object) to its input parameter. Sends a request and gets the response in the form of the XmlDocument object. Gets the request packet (a stream) to its input parameter. Validates the request packet using the agent_input.xsd validation schema. Invokes the Send(XmlDocument) member function. Gets the URI of the request packet (XML file) to its input parameter. Validates the request packet using the agent_input.xsd validation schema. Invokes the Send(XmlDocument) member function. Forms an HTTP request: puts the HTTP header and serialized XML packet to the object of type HttpWebRequest. Returns this object. Gets the URI of the agent_input.xsd schema and a string reader (with the URI of the XML packet to validate) to its input parameters. Validates the packet and returns it structured as a tree (an XmlDocument object).

The response packet received from the server can look as follows:
<?xml version="1.0"?> <packet version="1.6.2.0"> <domain> <add> <result> <status>ok</status> <id>6</id> <guid>5c0e3881-22a2-4401-bcc0-881d691bfdef</guid> </result> </add> </domain> </packet>
This packet returns the result of the add operation and ID and GUID of the domain just created. Code sample
using using using using using using using using System; System.Net; System.Text; System.IO; System.Xml; System.Xml.Schema; System.Security.Cryptography.X509Certificates; System.Net.Security;
Creating Client Software namespace PanelApiRpcClient { public class Request { // Public interface // public string Hostname Hostname public string Login Administrator's Login public string Password Administrator's Password public string Protocol Version Protocol.
= "localhost"; = "admin_login"; = "admin_passwd"; = "1.6.2.0";
// Panel // // // API RPC
// 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 Send(XmlDocument packet) { HttpWebRequest request = SendRequest(packet.OuterXml); XmlDocument result = GetResponse(request); return result; } public XmlDocument Send(Stream packet) { using (TextReader reader = new StreamReader(packet)) { return Send(ParseAndValidate(reader, InputValidationSchema)); } } public XmlDocument Send(string packetUri) { using (TextReader reader = new StreamReader(packetUri)) { return Send(ParseAndValidate(reader, InputValidationSchema)); } } // Private interface
Creating Client Software //
// Sending a request message // private HttpWebRequest SendRequest(string message) { HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AgentEntryPoint); request.Method = "POST"; request.Headers.Add("HTTP_AUTH_LOGIN", Login); request.Headers.Add("HTTP_AUTH_PASSWD", Password); request.ContentType = "text/xml"; request.ContentLength = message.Length; ASCIIEncoding encoding = new ASCIIEncoding(); byte[] buffer = encoding.GetBytes(message); using (Stream stream = request.GetRequestStream()) { stream.Write(buffer, 0, message.Length); } return request; } // 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

public string Login public string Password public string Protocol public XmlSchemaValidation Public ReadOnly Property AgentEntryPoint Public ReadOnly Property InputValidationSchema
Public ReadOnly Property OutputValidationSchema Public Function Send(ByVal packet As XmlDocument)
Holds the URL of the validation schema that will be applied to the response packet after it is received on the client side. Gets the request packet (in the form of the XmlDocument object) to its input parameter. Sends a request and gets the response in the form of the XmlDocument object. Gets the request packet (a stream) to its input parameter. Validates the request packet using the validation schema. Invokes the Send(XmlDocument) member function. Gets the URI of the request packet (XML file) to its input parameter. Validates the request packet using the validation schema. Invokes the Send(XmlDocument) member function. Forms an HTTP request: puts the HTTP header and serialized XML packet to the object of type HttpWebRequest. Returns this object. Gets the URI of the validation schema and a string reader (with the URI of the XML packet to validate) to its input parameters. Validates the packet and returns it structured as a tree (an XmlDocument object). Gets the HTTP request packet (HttpWebRequest object) to its input parameter. Sends the packet via HTTP, receives the response packet from the server, validates it using the validation schema, and returns the response XML packet structured as a tree (an XmlDocument object).
Public Function Send(ByVal packet As Stream)
Public Function Send(ByVal packetUri As String)
Private Function SendRequest(ByVal message As String) Private Function ParseAndValidate(ByVal xml As TextReader, ByVal schemaUri As String) Private Function GetResponse(ByVal request As HttpWebRequest)
Class Program implements the 'client' console application. Shared Sub Main(ByVal args As String()) An entry point to the PanelApiRpcClient application. Obtains an array of arguments (strings) to its input parameter. The arguments are: [0] - the host name (IP address) of the Panelmanaged server, [1] - the Panel administrator's login, [2] - the Panel administrator's password, [3] - the API RPC protocol used, [4] - a path of the XML file with an XML request packet. The function forms a request packet of type Request (see above), validates it, sends a request to the Panel, and prints out the resulting XML packet. Private Shared Function The function verifies the remote SSL RemoteCertificateValidation( certificate to authenticate the server. If the ByVal sender As Object, server is not authenticated, returns false. ByVal certificate As X509Certificate, ByVal chain As X509Chain, ByVal sslPolicyErrors As SslPolicyErrors) Private Shared Sub Validation error event handler. XmlSchemaValidation(ByVal sender As Object, ByVal e As ValidationEventArgs) Private Shared Sub PrintResult(ByVal document As XmlDocument) The function outputs the response packet (an XmlDocument object) to the console.

Creating Client Software request.ContentType = "text/xml" request.ContentLength = message.Length Dim bytes As Byte() = New ASCIIEncoding().GetBytes(message) Using stream As Stream = request.GetRequestStream stream.Write(bytes, 0, message.Length) End Using Return request End Function ' Parsing and validating packet ' Private Function ParseAndValidate(ByVal xml As TextReader, ByVal schemaUri As String) As XmlDocument Dim schemas As New XmlSchemaSet schemas.Add(Nothing, schemaUri) Dim settings As New XmlReaderSettings If (Not Me.XmlSchemaValidation Is Nothing) Then AddHandler settings.ValidationEventHandler, New ValidationEventHandler(AddressOf Me.XmlSchemaValidation.Invoke) End If settings.ValidationType = ValidationType.Schema settings.ValidationFlags = (settings.ValidationFlags Or XmlSchemaValidationFlags.ProcessSchemaLocation) settings.Schemas = schemas Dim document As New XmlDocument Using reader As XmlReader = XmlReader.Create(xml, settings) document.Load(reader) End Using Return document End Function Private Function GetResponse(ByVal request As HttpWebRequest) As XmlDocument Using response As HttpWebResponse = DirectCast(request.GetResponse, HttpWebResponse) Using stream As Stream = response.GetResponseStream Using reader As TextReader = New StreamReader(stream) return Me.ParseAndValidate(reader, Me.OutputValidationSchema) End Using End Using End Using End Function
End Class Friend Class Program Shared Sub Main(ByVal args As String()) If (args.Length < 5) Then Console.WriteLine("Usage: PanelApiRpcClient <Hostname> <Login> <Password> <Protocol> <Request>") Console.WriteLine(" ") Console.WriteLine(" Host name - The Panel's host name") Console.WriteLine(" Login - Administrator's login")
Console.WriteLine(" Password - Administrator's password") Console.WriteLine(" Protocol - API RPC protocol version") Console.WriteLine(" Request - Request file path (*.xml)") Else ' Verifies the remote Secure Sockets Layer (SSL) certificate ' used for authentication. ServicePointManager.ServerCertificateValidationCallback = New RemoteCertificateValidationCallback(AddressOf Program.RemoteCertificateValidation) Dim request As New Request request.XmlSchemaValidation = New ValidationEventHandler(AddressOf Program.XmlSchemaValidation) request.Hostname = args(0) ' "10.49.8.120"; request.Login = args(1) ' "admin"; request.Password = args(2) ' "setup"; request.Protocol = args(3) ' "1.6.2.0"; Dim packetUri As String = args(4) ' "request.xml"; Try Program.PrintResult(request.Send(packetUri)) Catch exception As Exception Console.WriteLine("Request error: {0}", exception.Message) End Try End If End Sub ' The following method is invoked by the RemoteCertificateValidationDelegate. Private Shared Function RemoteCertificateValidation(ByVal sender As Object, ByVal certificate As X509Certificate, ByVal chain As X509Chain, ByVal sslPolicyErrors As SslPolicyErrors) As Boolean If (sslPolicyErrors <> SslPolicyErrors.RemoteCertificateNotAvailable) Then Return True End If Console.WriteLine("Certificate error: {0}", sslPolicyErrors) ' Do not allow this client to communicate with unauthenticated servers. Return False End Function ' Private Shared Sub XmlSchemaValidation(ByVal sender As Object, ByVal e As ValidationEventArgs) Console.WriteLine("Validation error: {0}", e.Message) End Sub Private Shared Sub PrintResult(ByVal document As XmlDocument) Dim w As New XmlTextWriter(Console.Out)

Creating Client Software w.Formatting = Formatting.Indented document.WriteTo(w) w.Flush Console.WriteLine End Sub End Class End Namespace