Parallels Panel
Contents About This Document 3 Integration and Automation Capabilities 4 Command-Line Interface (CLI) 8 API RPC Protocol 9 Event Handlers 11 Panel Notifications 13 APS Packages 14
C H A P T E R 1 About This Document Purpose Scope This document addresses the basic needs of the following groups: Panel administrators who wish to automate routine operations. In this document, they will find alternatives to the GUI-based approach in Panel management. Integrators who build their application into Panel or set up interactions between Panel and third-party software. In this document, they will learn how to manipulate Panel objects and views, and handle Panel events. This document is an overview of all the available interfaces Panel reveals to third parties. It explains which technologies to use to carry out all types of typical interaction tasks (such as creation of objects, handling events, building your own controls into the GUI, etc.). From this document, you will learn conceptual details about each integration interface, see examples of them in use, and receive references to documents that contain more specific details. We would like readers to consider this document as a starting point in using Panel integration capabilities. The document does not provide extensive details, complex case studies, and working code samples. For such information, refer to the interfacespecific documentation: Panel 11 Command Line Reference for Linux Panel 11 Command Line Reference for Microsoft Windows API RPC Manual Parallels Panel Extensions SDK Customer and Business Manager SDK
C H A P T E R 2 Integration and Automation Capabilities This chapter provides a bird's eye view of Panel integration capabilities. Using these, you can control Panel objects, react to Panel events, make your applications available to Panel users, and build own GUI into Panel. In this chapter, we will briefly mention each of the integration capabilities and give our recommendations on when to use them. Performing Create, Read, Update, Delete (CRUD) Operations on Panel Objects A typical integration task is to manage Panel objects (service plans, customer accounts, and so on) more quickly, bypassing the Panel GUI. This task is relevant to administrators who manage a number of Panel servers and wish to automate day-today operations. It is also important for integrators who need to set up relations between objects in Panel and their application. There are two ways to complete the task: Make an appropriate Command Line Interface (CLI) call. Make an appropriate API RPC call. CRUD operations from CLI CLI is a set of utilities that perform almost all operations on Panel objects from the command line. A popular use of this interface is to replace typical GUI operations with utility calls, create shell scripts, and run them on demand. To call one of the utilities, you should have administrative permissions on Panel server. Each CLI utility specializes in operations on a certain Panel object (for example, a customer account) and has a specific syntax. You can learn about the syntax either from the built-in help or from the corresponding documentation. Learn more about how to get started using CLI in the chapter Command-Line Interface (CLI) (on page 8). For complete information about CLI, refer to Panel 11.5 Command Line Reference (Windows) and Panel 11.5 Command Line Reference (Linux). The major limitation of CLI is that you can only use it from a local server and only on behalf of the administrator. Alternatively, use the API RPC protocol if you require more flexibility, for example: Work with a remote Panel server. Manage objects located on several Panel servers at the same time. Run operations on behalf of a reseller or a customer.
Integration and Automation Capabilities 5 CRUD operations from API RPC The API RPC protocol allows you to manipulate Panel objects by exchanging XMLstructured packets with Panel. Each operation in API RPC is presented as an XML structure that you send to a certain HTTP endpoint. Panel receives the operation request, processes it, and also responds with an XML-structured packet. Each such response includes an operation status and operation-related details. For example, if you request information about a customer account, the account details will be returned in XML. An operation request packet also includes information about a Panel user on behalf of whom the operation is performed. This lets you automate the routines of any Panel user. Every operation available through CLI is also available through API RPC. This makes API RPC a more powerful tool, though the protocol implementation assumes programming efforts on your part (you should write a client application that sends and receives XML-over-HTTP packets). Learn more about how to get started using API RPC in the API RPC Protocol chapter (on page 9). For complete information about API RPC, refer to API RPC Manual. Monitoring Panel Events by Using Event Handlers Another typical integration task is to react to a particular operation on a Panel object. Examples of when such a reaction is important are as follows: Keep the app and Panel objects synced. For example, if your application needs to have the same list of customer accounts as Panel does, you should track the creation of customer accounts and create a new account every time Panel creates one. Generate custom statistics and notifications. For instance, one may need to receive an e-mail each time a service utilized by Panel is stopped. To track Panel operations and react correspondingly, employ event handlers. An event handler is a link between a particular operation and an instruction: When Panel completes the operation, it runs the linked instruction. The operation list is vast, so you can control almost all business logic operations. The instruction to trigger is usually a script or a binary. Depending on the operation, the instruction receives environmental variables that contain information about an operation target (Panel object) "before" and "after" the operation. For example, the environment variables keep "old" and "new" customer account names in case the account name was changed.
6 Integration and Automation Capabilities Learn more about how to get started using event handlers in the Event Handlers chapter (on page 11). For complete information about event handlers, refer to the Administrator s Guide, chapter Event Tracking. Receiving Notifications About Changes in Subscriptions, Sites, and E-mail Accounts with Panel Notifications The other way for you to integrate an application into Panel 10 is to register it as an additional service. Such services are assigned to service plans and receive notifications about changes to plans instances - subscriptions and related objects (sites and e-mail accounts). Registration is advisable only if you want to track these changes. For example, mail processing software should register in Panel Notifications to track changes in the e-mail account names of subscribers. In other words, Panel Notifications is an extension of the event handler mechanism. Learn more about how to get started with APS packaging in Panel Notifications (on page 13). For complete information about APS packaging, refer to Application Packaging Guide at http://www.apsstandard.org/doc/aps-format-1.2-packaging-guide/. Deliver Your Application as APS Package When a web application is ready to market, the most natural and convenient way for vendors to distribute the app is by adding it to the APS Catalog. The catalog is a part of Control Panel where customers can find an application and install it to their website. This ability to present third-party software in Panel might be interesting to integrators especially if their application uses Panel resources and has peculiarities in deployment and maintenance. APS - Application Packaging Standard - is a set of rules that regulates web application installation, updates, licensing, and removal. If you make your application APScompatible, you will not need to worry about application delivery because Panel will carry out all the installation and maintenance operations for you. Learn more about how to get started with APS packaging in the APS Packages chapter (on page 14). For complete information on APS packaging, refer to Application Packaging Guide at http://www.apsstandard.org/doc/aps-format-1.2-packaging-guide/.
Integration and Automation Capabilities 7 Build Your App into the Panel GUI Earlier versions of Panel provided the mechanism of extending its base functionality with plug-ins called extensions (former modules). These plug-ins could access Panel resources and have custom pages inside the Panel GUI. The earlier versions of SDK and the corresponding documents are incompatible with Panel 11, for this reason, we recommend that you refer to the Developing Extensions for Parallels Plesk Panel. For information about developing extensions for Customer and Business Manager, refer to the Customer and Business Manager SDK.
C H A P T E R 3 Command-Line Interface (CLI) The Command-Line Interface (CLI) is a set of command-line utilities that enable administrators to manage Panel server configuration, reseller and customer accounts, websites, and various services. The utilities can also be used for integration with thirdparty software. By default, the utilities are located in the following server directories: (On Linux servers) /usr/local/psa/bin (On Windows servers) C:\Program Files\Parallels\Plesk\bin Note: For convenience, the CLI directory is defined by the Windows environment variable %plesk_cli%. You can use it as an alternative to the absolute path. Each utility has its own application scope. For example, the dns utility is responsible for DNS zones, while the database utility lets you manage databases and DB user accounts. The functions carried out by utilities are reflected in their syntax. For example, this call creates a customer account with the john username and the mypass password in a Linux server. /usr/local/psa/bin/customer --create john -passwd mypass To find what operations and options each utility provides, call the utility with the -- help option or find more details in the CLI documentation. Complete information about CLI is available in two separate documents, for Windows and for Linux operating systems. The documents are called Panel 11.5 Command Line Reference (Windows) and Panel 11.5 Command Line Reference (Linux) respectively.
C H A P T E R 4 API RPC Protocol Panel provides the XML-based API to support interaction with third-party software. This interface lets you manage Panel objects - subscriptions, service plans, customer accounts, and so on. The interface is designed as a means of calling Panel operations remotely. This ability is reflected in its name - API RPC - Application Programming Interface for Remote Procedure Calls. How to work with API RPC To perform an operation through API RPC, you should send a specifically-structured HTTP message to a particular Panel endpoint (https://<your-host-or- IP>:8443/enterprise/control/agent.php). Panel receives the message, transforms the message to the operation instruction, attempts to perform the operation, and returns the operation status and details. Figure 1: Interaction between Parallels Panel and third-party client software An arbitrary HTTP message, a unit of interaction between third-party software and API RPC, can be represented graphically in the following way:
10 API RPC Protocol When forming the message, you should include Panel user credentials as specific HTTP headers and insert an XML presentation of the operation into the HTTP body. The format of such XML presentations and the format of the XML-like responses from Panel are covered by the API RPC protocol. From Theory to Practice In practical terms, to perform an operation through API RPC, you should do the following: 1. Create an XML presentation of the operation 2. Add the XML code to the body of an HTTP message 3. Add Panel user credentials to the message header (HTTP_AUTH_LOGIN and HTTP_AUTH_PASSWD) 4. Send this HTTP message to the Panel endpoint. Below, we provide more details on each of the steps. 1. Create an operation description. Construct the XML presentation using the Reference chapter of the latest version of the API RPC Manual. For example, if you wish to add a reseller plan, you should have an XML structure similar to this one: <packet version="1.6.3.0"> <reseller-plan> <add> <name>sample_plan</name> <ip-pool> <allocate-ip>2</allocate-ip> </ip-pool> </add> </reseller-plan> </packet> 2. Form an HTTP message and send it to Panel. There are a variety of libraries that let you easily create and send HTTP messages with custom headers and body. Depending on the programming language you use, utilize curl, HttpWebRequest, or other libraries. 3. Parse and analyze the Panel response. Panel responds to each API RPC request packet with a response packet that contains an operation status and details. For the details on structures Panel returns for each operation, consult the Reference chapter as well. If the operation status is OK, you have successfully performed the remote operation. Further details and instructions related to API RPC are available in the API RPC Manual. As we mentioned earlier, the document contains the explanation of the protocol, client software samples, and XML presentations of all operations supported by Panel through API RPC.
C H A P T E R 5 Event Handlers Event handlers are designed to help you receive notifications about Panel events. The most typical way to use them is as follows: you create a script to be executed upon a certain Panel event, and then you associate the event and your script using an event handler. Each time the event happens, the event handler will trigger your script.
12 Event Handlers The instruction to run is not necessarily a script. You can also associate event handlers with a system command or a binary file. In addition, there are two facts to consider before you start using event handlers: Event handlers trigger instructions on behalf of the Panel administrator. Event handlers have information about a related Panel object "before" and "after" an event. When an event occurs, event handlers receive the event details, and you can use these details in your instructions. For example, you can obtain the IP address which was added by the "adding an IP address" event. The event details are passed to your instructions as environment variables. Running scripts via event handlers For example, let's store the names of new customers on the file system. To do this, first we should find the environment variable that keeps a contact name. This variable is listed in the Administrator's Guide, Appendix > Customer account сreated. As you can see, the variable name is NEW_CONTACT_NAME. After you have the variable, write a shell script (say, write-names.sh) that accepts contact names from the variable and writes them to a file. In our example, the script code appears as follows: (For Linux) #!/bin/bash echo "Customer account has been created. Name: ${NEW_CONTACT_NAME}" >> /tmp/event_handler.log (For Windows) echo "Customer account has been created. Name: ${NEW_CONTACT_NAME}" >> c:\windows\temp\event_handler.log Panel should trigger this script after creating a customer account. To make this happen, associate the script and the "Customer account created" event. You can do this either from the Panel GUI or from the command line. (Panel GUI) In the Server Administration Panel, go to Tools & Utilities > Event Manager > Add New Event Handler, and follow the on-screen instructions. (Command line) Use the event_handler utility. For more details on event handlers, refer to the Administrator's Guide, the chapter Event Tracking. This chapter provides instructions on how to create event handlers and describes environment variables related to each Panel event.
C H A P T E R 6 Panel Notifications In the Panel hosting model, you can ship service plans with third-party services. These services are called additional services. For example, if you have a service that performs custom mail filtering, Panel lets you offer this service with, say, the Silver hosting plan, while it is not offered with others. Some additional services require information about instances of service plans - subscriptions and dependent objects (sites, e-mail accounts). If your service needs information about changes in these objects, register it in the Panel Notifications service (PN). Note: Events that PN maintains are beyond the scope of event handlers. PN works in a similar way to event handlers: You register your service as a PHP class, and Panel runs appropriate methods of this class when one of the events (maintained by the service) happens. The service maintains the following objects and actions upon them. Objects: subscription, site, e-mail account. Actions: create, modify, remove. After each action, PN offers these details about current object properties. Object subscription site e-mail account Details status, GUID status, name, GUID e-mail address Note: If you need further details about these objects, use an appropriate API RPC or CLI call to receive them. How to get started using PN To prepare a service for registration with PN, you should implement the appropriate PHP interface run an appropriate Panel call. The details of these operations are too technical to describe in this overview guide. To learn more about PN and service registration, refer to the Advanced Administration Guide for Parallels Plesk Panel for Linux.
C H A P T E R 7 APS Packages Suppose you have a web application and would like to know how to deliver it to Panel customers. The best way would be to put the app into the APS Catalog. For this, you should create an APS package from your app and have it certified for the APS Catalog. About creation of APS packages Creating an APS package, in technical terms, is the same as creating a ZIP archive that contains the content of your app and metadata. Panel uses this metadata to install and manage instances of the app. The metadata consists of the following: Application requirements - the technologies that the app will use; for example, PHP 5.3, Apache, MS SQL database, etc., and the way to use them (such as permissions to read or write to a particular directory). Application settings that a customer or the administrator can specify upon installation and configuration. Deployment and maintenance scripts that are invoked during application service provisioning, canceling, updating and reconfiguration. Miscellaneous information for proper presentation in Panel (such as the license agreement, icon, description, screen shots, category, etc.) When designing app metadata, you only need to specify the required information, so it should not take much time to prepare an APS package from a typical web app. For guidelines on how to prepare APS packages, read Application Packaging Guide at http://www.apsstandard.org/doc/aps-format-1.2-packaging-guide/. Please note, that Panel has only the partial support of APS. For a list of the limitations, read APS Support in Panel. How to succeed in APS certification Once you have prepared a package, the application must pass the certification procedure to appear in the APS Catalog. Obtaining certification requires these steps to be completed: Test your APS package with an APS-compliant product. Get access credentials to the APS Certification System. Upload the APS package for certification procedure. Resolve APS package issues if any have been found during certification. After receiving a certification level and passing all tests, request publication of the application.
APS Packages 15 For more information about certification, see the APS Package Certification Guide at http://www.apsstandard.org/doc/aps_package_certification_guide/index.htm.