Parallels Plesk Panel - 10.4 Administrator’s Guide

Parallels® Panel
Preface 5
Typographical Conventions ........................................................................................................... 5
Feedback ....................................................................................................................................... 6
About This Guide 7
Introduction to Panel 8
Installation and Upgrade Overview ............................................................................................. 11
Ports Used by Panel .................................................................................................................... 12
Licensing ..................................................................................................................................... 13
Virtual Hosts Configuration 14
Virtual Hosts and Hosting Types ................................................................................................. 17
Changing Virtual Hosts Settings Using Apache Configuration Templates.................................. 18
Template Execution Context ............................................................................................. 21
Example: Changing Default Apache Ports ........................................................................ 23
Predefining Virtual Hosts for New Sites ...................................................................................... 23
Default Structure of Panel Virtual Host ............................................................................. 24
Applying Custom PHP Settings on Domains with PHP in CGI/FastCGI Mode ........................... 27
Predefining Values for Customizable PHP Parameters .............................................................. 29
Analyzing Access and Errors ...................................................................................................... 30
Services Management 31
DNS ............................................................................................................................................. 32
FTP .............................................................................................................................................. 34
Mail Service ................................................................................................................................. 38
Restoring Mail Configuration ............................................................................................. 39
Installing Custom SSL Certificates for Qmail or Courier-IMAP Mail Servers .................... 40
Outgoing Mail from Exclusive IP Addresses ..................................................................... 44
Mailing Lists Management System .............................................................................................. 45
Configuring a Mailing List That Only Members are Allowed to Post to ............................. 46
Importing a List of E-mail Addresses into a Mailing List ................................................... 46
Web Apps .................................................................................................................................... 46
Multiple Web Apps in a Single Directory ........................................................................... 46
Hiding Commercial Apps ................................................................................................... 47
Spam Protection .......................................................................................................................... 48
Configuring SpamAssassin ............................................................................................... 49
Training SpamAssassin to Work with All Mail Accounts on the Server ............................ 50
Fighting Spam on a Qmail Mail Server ............................................................................. 51
Antivirus Support ......................................................................................................................... 53
Parallels Premium Antivirus .............................................................................................. 54
Kaspersky Antivirus ........................................................................................................... 56
System Maintenance 57
Preface 3
Managing Panel Objects Through the Command Line ............................................................... 57
Executing Custom Scripts on Panel Events ................................................................................ 58
Changing IP Addresses ............................................................................................................... 58
Changing Paths to Services ........................................................................................................ 59
Restarting Panel .......................................................................................................................... 60
Managing Services from the Command Line and Viewing Service Logs ................................... 60
Backing Up, Restoring, and Migrating Data 71
Backing Up Data .......................................................................................................................... 72
Backup Objects: Hierarchy and Volume ........................................................................... 73
Specifying Data for Backing Up ........................................................................................ 76
Defining Properties of Files That Compose the Backup ................................................... 82
Exporting Backup Files ..................................................................................................... 84
Defining How the Backup Process Is Performed .............................................................. 86
Backup Utility Commands and Options ............................................................................ 87
Restoring Data ............................................................................................................................. 91
Defining Objects for Restoration ....................................................................................... 92
Defining How the Restore Process is Performed.............................................................. 98
Conflict Resolution Rules and Policies ............................................................................. 99
Restoration Utility Commands and Options .................................................................... 120
Migrating Data ........................................................................................................................... 121
Statistics and Logs 122
Calculating Statistics from Logs ................................................................................................ 124
Recalculating Statistics for Previous Months ............................................................................ 124
Log Rotation .............................................................................................................................. 125
Resource Usage Reports .......................................................................................................... 127
Enhancing Performance 128
Reducing Resources Consumption in VPS Environments........................................................ 128
Setting Up VPS Optimized Mode in Parallels Vitruozzo Containers............................... 129
Setting Up VPS-Optimized Mode in Non-Virtuozzo Environments ................................. 131
Switching to Power User ........................................................................................................... 131
Increasing the Number of Domains that Panel Can Manage .................................................... 131
Running Apache with Piped Logs ................................................................................... 132
Recompiling Apache with More File Descriptors ............................................................ 132
Making Your Mail Spam Resistant ............................................................................................ 136
Apache Modules Switched Off in VPS-Optimized Mode 136
Enhancing Security 138
Restricting Script Execution in the /tmp Directory ..................................................................... 139
Configuring Site Isolation Settings ............................................................................................ 140
Protecting from Running Tasks on Behalf of root ..................................................................... 141
Customizing Panel Appearance and GUI Elements 142
Changing Panel Appearance and Branding with Custom Themes ........................................... 143
Hiding and Changing Panel GUI Elements ............................................................................... 144
Ways of Changing Panel Functionality ........................................................................... 145
Changing Panel Functionality ......................................................................................... 149
Preface 4
Localization 186
Troubleshooting 187
Cannot Access Panel ................................................................................................................ 188
Cannot Log In to Panel .............................................................................................................. 188
The Administrator's Password has been Forgotten .................................................................. 189
Panel in a Virtuozzo Container: Broken Layout ........................................................................ 190
EZ Templates Update Issues in Parallels Virtuozzo Containers ............................................... 192
Postfix Consumes Too Many Resources in a Container ........................................................... 192
Appendix A: Apache Configuration Files 193
Appendix B: Apache Templates Structure 195
Appendix C: Apache Configuration Variables 198
1. $VAR->server->..................................................................................................................... 199
2. $VAR->domain-> ................................................................................................................... 202
3. $VAR->subDomain-> ............................................................................................................ 207
4. $VAR->ipAddress-> .............................................................................................................. 208
Preface 5
In this section:
Typographical Conventions ............................................................................... 5
Feedback .......................................................................................................... 6
Formatting convention
Type of Information
Example
Special Bold
Items you must select, such as menu options, command buttons, or items in a list.
Go to the System tab.
Titles of chapters, sections, and subsections.
Read the Basic Administration chapter.
Italics
Used to emphasize the importance of a point, to introduce a term or to designate a command line placeholder, which is to be replaced with a real name or value.
The system supports the so called wildcard character search.
Monospace
The names of commands, files, and directories.
The license file is located in the
http://docs/common/licen ses directory.

Preface

Typographical Conventions

Before you start using this guide, it is important to understand the documentation conventions used in it.
The following kinds of formatting in the text identify special information.
6 Preface
Formatting convention
Type of Information
Example
Preformatted
On-screen computer output in your command­line sessions; source code in XML, C++, or other programming languages.
# ls –al /files
total 14470
Preformatted Bold
What you type, contrasted with on-screen computer output.
# cd /root/rpms/php
CAPITALS
Names of keys on the keyboard.
SHIFT, CTRL, ALT
KEY+KEY
Key combinations for which the user must press and hold down one key and then press another.
CTRL+P, ALT+F4

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.
About This Guide 7
Parallels Plesk Panel for Linux Advanced Administration Guide is a companion guide for the

About This Guide

Parallels Panel Administrator's Guide. It is intended for server administrators whose responsibilities include maintaining hosting servers and troubleshooting server software problems.
The guide provides step-by-step instructions for performing server management tasks that require use of Panel functionality other than the GUI and GUI-only tasks that administrators may need to perform only in rare and specific situations. Administrators can use several additional tools that are supplied in the standard Parallels Plesk Panel distribution package to add customized automation tasks, back up and restore data, and repair Panel components and system settings. The tools include a number of standalone applications, command-line utilities, and the ability to integrate custom scripting with Parallels Plesk Panel.
This guide contains the following chapters:
Introduction to Panel. Describes the main components and services operated by Panel,
licensing terms, and the ways to install and update Panel components.
Virtual Hosts Configuration. Describes virtual host concepts and their implementation in
Panel. Provides instructions on why and how to change their configuration.
Services Management. Contains descriptions of a number of external services used on
Panel server and instructions on how to configure and use them.
System Maintenance. Describes how to change the server host name, IP addresses, and
locations of directories for storing virtual host files, backups, and mail content. This chapter also introduces Panel's command-line tools, a mechanism for running scripts on Panel events, and the service monitor that allows monitoring and restarting of services without logging in to Panel.
Backing Up, Restoring, and Migrating Data. Describes how to back up and restore Panel data
by means of the command-line utilities pleskbackup and pleskrestore, and introduces the tools for migrating hosted data between servers.
Statistics and Logs. Describes how to run on demand statistics calculations on disk space
and traffic usage, and access web server logs.
Enhancing Performance. Provides information on how to improve Panel functioning by
means of software.
Enhancing Security. Provides instructions on how to protect the Panel server and sites
hosted on it from unauthorized access.
Customizing Panel Appearance and GUI Elements. Introduces Panel themes that can be used
to customize Panel appearance and branding and describes how to remove specific elements of the Panel GUI or change their behavior.
Localization. Introduces the methods of localizing the Panel GUI into languages for which
Parallels does not provide localization.
Troubleshooting. Describes how to troubleshoot malfunctions of Panel services.
Parallels Plesk Panel files can be divided into six major groups responsible for different
C H A P T E R 1

Introduction to Panel

aspects of Panel work. The diagram below shows these groups (components of the Panel) and the connections they have to each other and to external services that Panel manages.
Introduction to Panel 9
Panel components are as follows:
Panel core. The core processes requests that Panel receivess from the Panel GUI,
command line interface, and API RPC. The core contains scripts, binary files and other resources used to link Panel components with each other and with external services.
Panel database psa. The database stores information about Panel objects, such as
IP addresses, domains, user accounts, and so on.
sw-cp-server - a web server based on lighttpd. This serves requests to the Panel
GUI.
Panel GUI - a web interface provided with sw-cp-server. The GUI is the main means
of interaction with Panel.
Command line utilities. The command line interface allows integration of third-party
software with Panel objects. In addition, it is a way for administrators to manage Panel through the server shell. For more information on the Panel command line interface, refer to Panel Command Line Reference.
API RPC. This interface is another way to integrate third-party software with Panel.
It allows Panel objects to be managed remotely by sending specifically structured XML packets and receiving responses from Panel. For more information on API RPC, refer to API RPC Developer's Guide and API RPC Protocol Reference.
The Most Important Files and Directories
Parallels Plesk Panel for Linux installs its main components into the following directory:
On RPM-based operating systems: /usr/local/psa
On DEB-based operating systems: /opt/psa
This directory (main Panel directory) contains Panel core files, command line utilities, log files and so on.
In addition, Panel creates files and directories outside the main directory. The list below contains those that you are likely to use when administering Panel.
The main configuration file containing paths to utilities, services and packages used
by Panel:
/etc/psa/psa.conf
The initialization script for opening and closing services during server startup and
shutdown procedures: /etc/init.d/psa
Initialization scripts for starting and stopping services with xinetd:
/etc/xinetd.d/smtp_psa
/etc/xinetd.d/smtps_psa
/etc/xinetd.d/poppassd_psa
/etc/xinetd.d/ftp_psa
Find more information on xinetd at http://www.xinetd.org/.
10 Introduction to Panel
Panel database:
In this chapter:
Installation and Upgrade Overview ....................................................................11
Ports Used by Panel ..........................................................................................12
Licensing ...........................................................................................................13
/var/lib/mysql/psa/
Backup files:
/var/lib/psa/dumps/
Introduction to Panel 11

Installation and Upgrade Overview

The most common way of installing and upgrading Parallels Plesk Panel is to use the Parallels Installer utility. This utility connects to the Parallels Updates server where the Panel distribution packages are stored. It then retrieves, downloads, and installs Panel. You can download the Parallels Installer utility from
http://www.parallels.com/eu/download/plesk/products/.
For detailed instructions on how to use Parallels Installer, refer to Parallels Plesk Panel
10.4 Installation and Upgrade Guide.
For Linux servers, there is another tool to install Panel - the one-click installer utility. This allows the latest version of Panel for your operating system and platform to be installed in one step. For detailed instructions on how to use the Parallels Installer and one-click installer utilities, refer to Parallels Plesk Panel 10.4 Installation and Upgrade Guide.
Installing Panel in the Parallels Virtuozzo Containers Environment
If you operate in the Parallels Virtuozzo Containers (PVC) environment, you can use application templates for installing Panel on containers.
When the application templates are installed on a PVC hardware node, they allow you to easily deploy the application on as many containers as required, saving system resources such as disk space.
You can obtain the Panel templates at
http://www.parallels.com/eu/download/plesk/products/ or download them using the
PVC command line utility call vzup2date -z (available on PVC 4 and above).
For more information on installing Panel on PVC, read the Parallels Plesk Panel Deployment Guide, chapter Deployment Inside Parallels Virtuozzo Containers.
Checking Potential Issues Before Upgrading to Panel 10
If you use Parallels Plesk Panel 9 or earlier and want to upgrade it to Panel 10, you may encounter problems due to changes in the business model of Panel 10. In particular, it might be impossible to transfer some settings and business objects.
To efficiently anticipate or resolve the problems, we offer a tool called plesk101_preupgrade_checker.php. This checks potential business logic issues with upgrading to Panel 10 and gives recommendations that help you fix the possible problems related to transition of Panel objects.You can download the tool and find descriptions of the report messages at http://kb.parallels.com/9436.
12 Introduction to Panel

Ports Used by Panel

Service name
Ports used by service
Administrative interface of the Panel
TCP 8443, 8880
VPN service
UDP 1194
Web server
TCP 80, TCP 443
FTP server
TCP 21
SSH (secure shell) server
TCP 22
SMTP (mail sending) server
TCP 25, TCP 465
POP3 (mail retrieval) server
TCP 110, TCP 995
IMAP (mail retrieval) server
TCP 143, TCP 993
Mail password change service
TCP 106
MySQL server
TCP 3306
MS SQL server
TCP 1433
PostgreSQL server
TCP 5432
Licensing Server connections
TCP 5224
Domain name server
UDP 53, TCP 53
Parallels Plesk Panel is middleware between end users and external services such as FTP, mail, DNS and others. Due to technical limitations, Panel is able to interact with these services only if they are available on certain ports.
The list below provides information about services managed through Panel and about ports on which they should be available for proper interaction with Panel. If you use a firewall, make sure that the connections to all of these ports are allowed for corresponding Panel services.
Introduction to Panel 13

Licensing

After you install Parallels Plesk Panel, a trial license key for 14 days is installed by default. To continue using Panel after the trial license key expires, you should obtain a lease license key or purchase a permanent license key.
A leased license means that you pay for a limited time during which you can use Panel, say, for a couple of months. During the lease period, Panel will perform free monthly updates of your license key. The lease license includes free upgrades to all major new versions of Panel.
The permanent license means that you buy a lifetime Panel license. A permanent license is updated every three months for free. Upgrading a Panel installation with a permanent license to the next major version requires a separate payment unless you use Software Update Service (SUS). See http://www.parallels.com/support/sus/ for more information on SUS.
Panel license keys have a grace period of 10 days before the expiration date. During the grace period, Panel makes daily attempts to update the license key automatically. If an automatic update fails, Panel notifies the administrator. If you do not update a license key during the grace period, it expires and blocks Panel functions until you install a valid license key.
Panel defines whether it needs to update the license key using the update-keys.php utility located in the
$PRODUCT_ROOT_D/admin/plib/DailyMaintainance/directory, where the $PRODUCT_ROOT_D is /usr/local/psa for RPM-based systems or /opt/psa on
DEB-based systems. This utility checks the license grace period and expiration date and tries to retrieve a new license key or blocks Panel.
Panel runs the utility every day as a part of the daily maintenance script. If you want to check for license updates, you can run the script manually by executing the command
$PRODUCT_ROOT_D/bin/sw-engine-pleskrun $PRODUCT_ROOT_D/admin/plib/DailyMaintainance/script.php.
You can retrieve and manage license keys through the Panel GUI. The information about the current license key and controls for managing license keys are located in Server Administration Panel > Tools & Settings > License Management.
Parallels Plesk Panel for Linux uses the Apache web server for websites hosting.
C H A P T E R 2

Virtual Hosts Configuration

Apache itself does not operate with websites; it manages virtual hosts - web resources identified either by an IP address or a host name. When creating a site, Panel adds a new virtual host to Apache so that the site becomes available through the web server. Panel resides on a virtual host too; this host is called the default virtual host.
When you add a site in Panel, you select one of the hosting types to use with it: web page hosting or forwarding. In terms of Apache, you associate the site with a virtual host of one of three configurations (website hosting, standard forwarding, and frame forwarding). To learn the differences between these configurations, see the section Virtual Hosts and Hosting Types (on page 17).
Sites are linked to virtual hosts, so if you want to add some feature provided by Apache but not available through the Panel GUI, you should change the virtual host settings using Apache configuration templates. Based on these templates, Panel partly re­generates virtual hosts, so you should follow certain rules when modifying the configuration; otherwise, some of your changes might be lost. Next in this chapter, we will discuss virtual hosts in more detail and provide guidelines on how to modify them safely. To learn more on this point, refer to the section Configuring Virtual Hosts.
Panel creates virtual hosts for websites based on virtual host templates. These templates predefine the content that will be included in each new virtual host. Learn how to change virtual host templates in the section Predefining Virtual Hosts for new Sites (on page 23).
You can get information on access to each virtual host and Apache errors that have occurred on the host from Apache logs. Learn more about log files location and rotation settings in the section Analyzing Access and Errors (on page 30).
Virtual Host IP Addresses
The term virtual host refers to the practice of running more than one website on a single server or IP address. For example, Apache can manage two websites, example1.com and example2.com, even if they use a single IP address. Each of these sites is hosted on a separate virtual host.
There are two types of virtual host, each with different methods of requests routing:
IP-based. Each virtual host has a separate IP address. Apache defines the
requested host based on the host IP address.
Name-based. This supposes that several virtual hosts share the same IP address.
To define a requested host, Apache parses the domain name.
Virtual Hosts Configuration 15
Parallels Plesk Panel uses the name-based approach. In addition, Panel provides an option to allocate separate IP addresses to customers who do not want to share their IP address with others. To implement this option, there are two types of IP address in Panel:
Dedicated IP addresses that have a single owner.  Shared IP addresses that you can allocate to any number of customers.
Resolving Requests to Web Servers
When a client requests a certain domain, Apache parses the requested domain name. Then Apache searches for the virtual host with the requested domain on the IP address specified in the request. If the host exists, Apache sends the requested files from this host to the client.
If the requested virtual host is not found, Panel uses the following entities to resolve the request:
1. Default domain. This can be created for a specific IP address. If a request to this IP address contains the name of a non-existent domain, Panel redirects this request to the default domain.
2. Default virtual host. This accepts all requests to server IP addresses that could not be directed to any default domain.
Hosting Types
Depending on how you intend to use a domain, for example, to host a site or to forward HTTP requests to another domain, you can choose from three hosting types that define the structure of a virtual host created for this domain. The hosting types are the following:
Website hosting. When you choose this type of hosting, Panel creates a virtual host
(disk space on the local server) for a customer. Customers store their files on a virtual host and run their websites without having to purchase a server and dedicated communication lines.
Standard forwarding. In this case Panel creates a reduced virtual host that does not
store its owner's files and directories.This host is used for redirecting requests to another network resource. When end users try to access the domain, Panel forwards them to another URL. This URL will be shown in their browsers.
Frame forwarding. In this case Panel creates a reduced virtual host that does not
store its owner's files and directories. Unlike standard forwarding, frame forwarding virtual hosts show the requested URL in the browser, not the actual URL. Panel uses the HTML frames to show the pages of another site with the requested URL.
Learn how to change a domain's hosting type in the section Changing Hosting Type (on page 17).
16 Virtual Hosts Configuration
In this chapter:
Virtual Hosts and Hosting Types ....................................................................... 17
Changing Virtual Hosts Settings Using Apache Configuration Templates .......... 18
Predefining Virtual Hosts for New Sites ............................................................. 23
Applying Custom PHP Settings on Domains with PHP in CGI/FastCGI Mode ... 27
Predefining Values for Customizable PHP Parameters ..................................... 29
Analyzing Access and Errors ............................................................................. 30
Virtual Hosts Configuration 17

Virtual Hosts and Hosting Types

Depending on how you intend to use a site created in Panel, for example, to host web pages or to forward HTTP requests to another site, you can choose from three hosting types that define the structure of a virtual host created for this site. The hosting types are the following:
Website hosting. When you choose this type of hosting, Panel creates a virtual host
(disk space on the local server) for a customer. Customers store their files on a virtual host and run their websites without having to purchase a server or dedicated communication lines.
Standard forwarding. In this case, Panel creates a reduced virtual host that does
not store its owner's files and directories.This host is used for redirecting requests to another network resource. When users try to access the domain, Panel forwards them to another URL. This URL will be shown in their browsers.
Frame forwarding. In this case, Panel creates a reduced virtual host that does not
store its owner's files and directories. Unlike standard forwarding, frame forwarding virtual hosts show the requested URL in a browser, not the actual one. Panel uses HTML frames to show the pages of another site with the requested URL.
The virtual host structure differs depending on hosting type:
Domains with a website hosting type have a directory called document root where
the website files are stored. The configuration of such a virtual host looks like this:
<VirtualHost 10.0.69.4:80> ServerName "domainXX.tst:443" ServerAlias "www.domainXX.tst" UseCanonicalName Off <IfModule mod_suexec.c> SuexecUserGroup "domainXX.tst" "psacln" </IfModule> ServerAdmin "admin@mailserver.tst" DocumentRoot "/var/www/vhosts/domainXX.tst/httpdocs" CustomLog /var/www/vhosts/domainXX.tst/statistics/logs/access_ssl_log plesklog ErrorLog "/var/www/vhosts/domainXX.tst/statistics/logs/error_log"
......................................................................
..
Standard forwarding domains just contain a forwarding address in the configuration
file. No space for storing files is allocated. The configuration of such a virtual host looks like this:
<VirtualHost 10.0.69.2:80> ServerName "SFdomain.tst.tst" ServerAlias "www.SFdomain.tst.tst"
ServerAdmin "admin@mailserver.tst" RedirectPermanent / "http://easytofinddomain.tst/" </VirtualHost>
18 Virtual Hosts Configuration
Frame forwarding domains have a document root with a single file index.html
with the <FRAMESET> tag that defines the frame and address of the website to show in the frame. Therefore, the configuration of a frame forwarding virtual host resembles website virtual host configuration:
<VirtualHost 10.0.69.2:80> ServerName "FFdomainXX.tst" ServerAlias "www.FFdomainXX.tst"
ServerAdmin "admin@mailserver.tst" DocumentRoot "/var/www/vhosts/FFdomainXX.tst/httpdocs" <IfModule mod_ssl.c> SSLEngine off </IfModule> </VirtualHost>
When you create a website inside a subscription in Server Administration Panel, the domain hosting type is set to website hosting. When you create a domain in Control Panel, you can set a different hosting type. Domain owners are free to change the hosting types of their domains whenever they wish.
To change the hosting type of a domain, open Control Panel > Websites & Domains, click the domain name, and go to the Hosting Type > Change.

Changing Virtual Hosts Settings Using Apache Configuration Templates

You can change the settings of virtual hosts running on the Panel server, for example, set custom error pages (similar for all virtual hosts), or change the port on which the hosted site is available.
These settings are stored in a set of Apache and virtual hosts configuration files. To reduce the risk of errors during modification of Apache configuration files, Parallels Plesk Panel provides a mechanism for changing the Apache and virtual host configuration - Apache configuration templates. These templates are files, based on which Panel re-generates certain Apache configuration files. Other Apache configuration files are generated automatically and cannot be changed. The hierarchy of the Apache configuration files generated from Panel automatically and from templates is shown in the Appendix A: Apache Configuration Files (on page 193).
Apache configuration files support versioning. This allows you to roll back to a previous configuration if the new one contains errors.
The default templates are located in
$PRODUCT_ROOT/admin/conf/templates/default/, where the $PRODUCT_ROOT_D is /usr/local/psa for RPM-based systems or /opt/psa on
DEB based systems.
Virtual Hosts Configuration 19
To introduce your customizations to the configuration, copy the templates you need to the $PRODUCT_ROOT/admin/conf/templates/custom/ directory and modify them, preserving the directory structure, and then modify these copies. You can create new templates from scratch and place them in the custom/ directory according to the default structure.
Important: Do not change the default templates. All template customizations must be performed in the $PRODUCT_ROOT/admin/conf/templates/custom/ directory, and the default templates structure and content must be kept unchanged, since there are no specific tools to undo the changes.
To remove customizations and restore the default configuration, just delete the custom template files.
To change virtual hosts configuration using Apache configuration
templates:
1. (If there is no such directory yet) Create the
$PRODUCT_ROOT/admin/conf/templates/custom/ folder.
2. Copy and paste the required templates from default/ to custom/ preserving the directory structure. You can find the complete list of templates and their descriptions in the Appendix B: Apache Templates Structure (on page 195).
3. Modify the templates. See the details in the Templates Execution Context section (on page 21).
4. Check that the modified templates are valid PHP files:
# php -l <file-name>
5. Generate new configuration files:
# httpdmng <command>
Where <command> is one of the following:
--reconfigure-server generates sever-wide configuration files.
--reconfigure-domain <domain-name> generates files for a specified
domain.
--reconfigure-all generates all configuration files.
Note: Panel generates configuration files automatically upon a variety of events. For example, if a website's hosting settings are changed - say PHP is enabled ­configuration for this website is generated anew.
20 Virtual Hosts Configuration
Example: modifying error pages:
In this section:
Template Execution Context ..............................................................................21
Example: Changing Default Apache Ports .........................................................23
1. Copy the error pages template to the custom/ directory:
# mkdir -p /usr/local/psa/admin/conf/templates/custom/domain/service/ # cp /usr/local/psa/admin/conf/templates/default/domain/service/er rordocs.php /usr/local/psa/admin/conf/templates/custom/domain/service/err ordocs.php
2. Edit the
/usr/local/psa/admin/conf/templates/custom/domain/ser vice/errordocs.php file.
3. Check the validity of the file and generate new configuration files.
Virtual Hosts Configuration 21

Template Execution Context

In essence, configuration templates are PHP files which, when executed, output web server configuration files. The templates are executed in the environment where the specific variables $VAR and $OPT are available.
$VAR is an object containing the data model which should be applied to a template. The variable contains an essential set of parameters defining the content of web server configuration. The detailed structure of the array is presented in the Appendix A: Apache Configuration Variables (on page 198).
The most important function is IncludeTemplate() which is part of the $VAR array. The function allows including templates one into another, and it is defined as
IncludeTemplate($templateName, $OPT, $metainfo)
where
 $templateName - string denoting name of included template. Required
 $OPT - an associative array which passes values to a template. Optional
$metainfo - an associative array which defines certain aliases in the template
context. Optional
The basic function usage is as follows:
## source: default/server.php
<?php echo $VAR->includeTemplate('server/tomcat.php') ?>
A text generated by the included template (server/tomcat.php) will be included in the configuration file.
In cases when the text generated by an included template should depend on the context, say, when iterating over a set of values, it is possible to pass additional parameters to the template.
## source: default/server.php
<?php echo $VAR->includeTemplate('service/php.php', array( 'enabled' => false, )) ?>
Here, we included the service/php.php template and passed the value 'enabled' => false to it. In the template being included the passed value is available in the variable $OPT:
## source: service/php.php
<?php if ($OPT['enabled']) { // it is required to detect 'enabled' echo "php_admin_flag engine on\n"; if (!array_key_exists('safe_mode', $OPT) || $OPT['safe_mode']) {
// optional parameter 'safe_mode'
echo "php_admin_flag safe_mode on\n"; } else { echo "php_admin_flag safe_mode off\n";
22 Virtual Hosts Configuration
} if(array_key_exists('dir', $OPT) && $OPT['dir']) { // optional
parameter 'dir'
echo "php_admin_value open_basedir {$OPT['dir']}:/tmp\n"; } } else { echo "php_admin_flag engine off\n"; } ?>
The code in this sample will generate two different blocks of text depending on which value of the 'enabled' parameter is passed.
Note that $VAR, which contains the data model, can be used in templates being included as well. Some values of $VAR are defined using the content of $metainfo. For details on possible $metainfo content and how it affects a template context, refer to Appendix A: Apache Configuration Variables (on page 198). For example, by defining the subDomainId value in the $metainfo parameter, it is possible to set an exact subdomain model available at $VAR->subDomain in a template being included:
## source: default/domainVhost.php
<?php
//going through all subdomains of current domain
foreach ($VAR->domain->physicalHosting->subdomains as $subdomain) { if ($subdomain->ssl) { //if SSL is enabled on a subdomain //include configuration for subdomain with enabled SSL echo $VAR->includeTemplate('domain/subDomainVirtualHost.php', array( 'ssl' => true, // passing $OPT['ssl'] = true ), array( 'subDomainId' => $subdomain->id, // define target
subdomain for which a configuration file is being built
)); }
//include configuration for subdomain with disabled ssl echo $VAR->includeTemplate('domain/subDomainVirtualHost.php', array( 'ssl' => false, ), array( 'subDomainId' => $subdomain->id, )); } ?>
## source: domain/subDomainVirtualHost.php
ServerName "<?php echo $VAR->subDomain->asciiName ?>.<?php echo $VAR­>domain->asciiName ?>:<?php echo $OPT['ssl'] ? $VAR->server­>webserver->httpsPort : $VAR->server->webserver->httpPort ?>"
Virtual Hosts Configuration 23

Example: Changing Default Apache Ports

Changing the default http and https ports of a web server is useful when employing an additional web server for caching purposes. For example, Nginx web server listens on the default ports (80 http, 443 https), serves static content, say, all requests but PHP, and redirects PHP requests to Apache. In turn, Apache web server listens on custom ports (say, 8888 and 8999) and serves dynamic content - PHP requests.
To change the Apache HTTP port:
Find all occurrences of the string $VAR->server->webserver->httpPort and replace them with the required port number enclosed in quotation marks, for example: "3456".
To change the Apache HTTPS port:
Find all occurrences of the string $VAR->server->webserver->httpsPort and replace them with the required port number enclosed in quotation marks, for example: "4567".
Example
To make Apache listen to HTTP requests on port 3456, and HTTPS on 4567, make the changes described above in all templates.
For example, in domain/domainVirtualHost.php:
<VirtualHost <?php echo $VAR->domain->physicalHosting->ipAddress­>address ?>:<?php echo $OPT['ssl'] ? $VAR->server->webserver­>httpsPort : $VAR->server->webserver->httpPort ?>> ServerName "<?php echo $VAR->domain->asciiName ?>:<?php echo $OPT['ssl'] ? $VAR->server->webserver->httpsPort : $VAR->server­>webserver->httpPort ?>"
change to
<VirtualHost <?php echo $VAR->domain->physicalHosting->ipAddress­>address ?>:<?php echo $OPT['ssl'] ? "4567" : "3456" ?>> ServerName "<?php echo $VAR->domain->asciiName ?>:<?php echo $OPT['ssl'] ? "4567" : "3456" ?>"

Predefining Virtual Hosts for New Sites

When Panel creates a site, one of the operations it carries out is to create a directory structure for the site and fill the directories with some initial content. These directories are located in the corresponding virtual host directories ­/var/www/vhosts/<domain_name>, where domain_name is the name of a corresponding domain. By default, Panel creates similar sets of files and directories inside each virtual host directory. See the section Default Structure of Panel Virtual Host (on
page 24) for a complete list of these files and directories.
24 Virtual Hosts Configuration
If you want to change the set of files and directories that are automatically included in
In this section:
Default Structure of Panel Virtual Host .............................................................. 24
Directories Tree
User
Group
Permis sions
Description
/<VHOST >
root
root
755
/anon_ftp
user
psaser v
750
Anonymous FTP files.
new sites, for example, so as to include some useful scripts or change the error pages, you can define a custom virtual host template. Later, you can replace, edit or remove files generated by the template from any site.
In addition, resellers can set separate virtual hosts templates for their customers.
To define a custom virtual host template:
1. On your local file system, create the required directories: httpdocs, httpsdocs, cgi-bin, anon_ftp, error_docs.
2. Place the files you need into these directories. Place web pages in
httpdocs and httpsdocs directories, scripts in the cgi-bin directory, and custom error messages in the error_docs directory.
You can use the default files stored in the /var/www/vhosts/skel/0.
3. Pack the directories and files into an archive in tgz, tar, tar.gz, or zip format.
Make sure that the directories are in the root of the archive file and not in a subdirectory.
4. Upload the archive to Panel though the GUI: Server Administration Panel > Tools & Settings > Virtual Host Template > Browse.
To switch back to the default virtual host template, go to Tools & Settings > Virtual Host Template and click the Default button.
Note: Subdomains have the same status with additional domains and employ the same directory structure. Thus, they have a separate directory in /var/www/vhosts and their own configuration files, like php.ini or vhost.conf.

Default Structure of Panel Virtual Host

The following table shows the default structure of a virtual host created by Panel and permissions set for its content:
Virtual Hosts Configuration 25
/cgi-bin
user
psaser v
750
CGI scripts. /conf
root
psaser v
755
Configuration files.
/error_docs
root
psaser v
755
Error messages files.
<doc>.html
user
psaser v
755
/etc
root
root
755
Chroot environment directory.
/httpdocs
user
psaser v
750
HTTP documents.
/httpsdocs
user
psaser v
750
HTTPs documents.
Note: This directory is not present in new installations, only in upgrades from previous versions
/pd
root
psaser v
750
Passwords to protected directories.
d..<dir1>@<d ir2>
apache
apache
400
/private
user
root
700
User’s private
storage.
/statistics
root
psaser v
550
Statistics directory
/anon_ftpstat
root
root
755
Anonymous FTP statistics.
/ftpstat
root
root
755
FTP user statistics.
/logs
root
root
755
Virtual host logs.
/webstat
root
root
755
HTTP user statistics.
/webstat-ssl
root
root
755
HTTPS user statistics.
/usr
root
root
755
Chroot environment directory.
/web_users
root
psaser v
755
Web users directory.
26 Virtual Hosts Configuration
/<web_user>
web_us er
psaser v
750
/<subdomain >
user
psaser v
750
HTTP and HTTPs documents of a subdomain
(since Panel
10.0)
/subdomains
root
psaser v
755
Service directory.
Note: The directory is used for compatibility with earlier Panel versions .
Virtual Hosts Configuration 27

Applying Custom PHP Settings on Domains with PHP in CGI/FastCGI Mode

Since Panel 10.3, administrators can specify custom PHP settings individually for each domain (virtual host in Apache terms). The typical usage of this feature is to allocate certain resources (like RAM consumed by PHP) to a particular site or to allow some configuration changes to meet needs of a certain web app.
Server-Wide and Domain-Level PHP Settings
The resulting PHP configuration for each domain is defined on two levels: Server-wide and domain-level. The domain-level configuration is of higher priority and it overwrites the server-wide configuration. Here are our recommendations on changing PHP settings in Panel.
Change server-wide settings if you need to change certain PHP settings on all
domains. The settings file path: /etc/php.ini.
Change domain-level settings if you want the changes to be applied only to a
certain domain. The changes will take effect only on domains with PHP running in the CGI or FastCGI mode. The settings file path: /var/www/vhosts/<domain_name>/conf/php.ini, where <domain_name> is the name of a corresponding domain.
Important: The domain-level changes are not applied automatically. To make Panel start using the new settings, notify it from the GUI. For this, change the PHP support option to a different value, save it, and roll back to the original state. To reach PHP support, go to Websites & Domains and click the domain name, the subject of new PHP settings.
Verifying the Results of Domain-Level Configuration
When you apply settings from your custom file, Panel merges them from these sources:
Customer's domain-level settings they can toggle from Panel GUI, actually:
The PHP safe mode toggle.
The path to the cgi-bin directory.
Domain-level settings from the /conf/ directory. They override the customer's
settings.
The result is put to /var/www/vhosts/<domain_name>/etc/php.ini for the further use. Use this file to verify that the results fit your expectations.
28 Virtual Hosts Configuration
Changing PHP Settings of All New Domains
If you want to use custom PHP settings for all newly created websites, copy your custom php.ini file to the conf directory of a virtual host template. For more information on host templates, refer to the section Predefining Virtual Hosts for New Sites (on page 23).
Virtual Hosts Configuration 29

Predefining Values for Customizable PHP Parameters

Panel allows to define custom PHP configuration for a certain service plan, add-on plan, subscription, website, and even subdomain. For this purpose, the Panel GUI exposes 16 most often used PHP parameters that allow customization. The administrator or a customer can set the value of each parameter either by selecting a value from a preset, typing a custom value, or leaving the default value. In the latter case, Panel takes the parameter value from the server-wide PHP configuration.
Using the $PRODUCT_ROOT/admin/conf/panel.ini file you can specify what PHP parameters values will be available in the preset and toggle the visibility of the custom value field.
Defining the Preset Values To set the list of predefined values for a certain PHP parameter, add the line of the following type to the [php] section of the panel.ini file:
settings.<parameter_group>.<parameter_name>.values[]=<value>
where
<parameter_group> - a group of a PHP parameter: performance for the
performance PHP settings and general if the parameter is placed in to the common group. For more information about the groups of PHP parameters, read the Administrator's Guide, Customizing PHP Configuration.
<parameter_name> - a name of a PHP parameter. Use the same syntax as in
php.ini.
<value> - a parameter's value added to the preset. Use the same syntax as in
php.ini.
Add such line for each value in the preset. For example, if you want Panel users to choose the value of the memory_limit parameter between 8M and 16M, add the following lines to panel.ini:
[php] settings.performance.memory_limit.values[]=8M settings.performance.memory_limit.values[]=16M
30 Virtual Hosts Configuration
Hiding the Custom Value Fields
To hide the field that allows entering the custom value for a certain PHP parameter, add the line of the following type to the [php] section of the panel.ini file:
settings.<parameter_group>.<parameter_name>.custom=false
where
<parameter_group> - a group of a PHP parameter: performance for the
performance PHP settings and general if the parameter is placed in to the common group. For more information about the groups of PHP parameters, read the Administrator's Guide,
<parameter_name> - a name of a PHP parameter. Use the same syntax as in
php.ini.
For example, if you do not want Panel users to set custom values to the memory_limit parameter, add the following line to panel.ini:
[php] settings.performance.memory_limit.custom=false
To switch the custom value field back on, replace false with true.

Analyzing Access and Errors

For each site, Apache writes access and error information to log files. Each site has two log files - access_log and error_log, which store information on access to that site and errors respectively. Apache log files for each site are located in the
/statistics/logs subdirectory of the virtual host directory /var/www/vhosts/<domain_name>, where domain_name is the name of a
corresponding domain.
To save disk space, Panel rotates Apache logs. Learn how to change log rotation parameters in the Log rotation (on page 125) section.
To enable basic hosting services and functions on a Panel-managed server, the Panel
In this chapter:
DNS .................................................................................................................. 32
FTP ................................................................................................................... 34
Mail Service....................................................................................................... 38
Mailing Lists Management System .................................................................... 45
Web Apps ......................................................................................................... 46
Spam Protection ................................................................................................ 48
Antivirus Support ............................................................................................... 53
C H A P T E R 3

Services Management

distribution package includes several third-party software applications that are installed along with Parallels Plesk Panel. These applications are responsible for providing various hosting services such as DNS, e-mail, FTP, and others.
All software components shipped with Panel can be installed and updated by means of Parallels Installer. These components are listed at
http://download1.parallels.com/Plesk/PP10/10.4.0/release-notes/parallels-plesk-panel-
10.4.0-for-linux-based-os.html#4.
You can also install and manage through Parallels Plesk Panel many other third-party applications that are not included in the Parallels Plesk Panel distribution package. For the complete list of third-party applications currently supported by Panel, refer to
http://download1.parallels.com/Plesk/PP10/10.4.0/release-notes/parallels-plesk-panel-
10.4.0-for-linux-based-os.html#5.
This chapter provides detailed descriptions of different external components used for providing hosting services on a Panel server.
32 Services Management
DNS
Parallels Plesk Panel for Linux works in cooperation with the BIND (or named) domain name server that enables you to run a DNS service on the same machine on which you host websites.
When you add a new domain name to Panel, it automatically generates a zone file for this domain in accordance with the server-wide DNS zone template and registers it in the name server's database, then instructs the name server to act as a primary (master) DNS server for the zone.
Configuring DNS
You can change the name server settings by editing configuration file /var/named/run-
root/etc/named.conf (/etc/named.conf is a soft link to it). This file consists of the following
parts:
General Settings containing the following sections:
The Options section contains the directory option referring to /var, which is used
as the base directory relative to $ROOTDIR (which is /var/named/run-root by default) for all other files used below. It also sets the location where named will store its PID.
The key and control sections define a shared key for managing named with the
rndc utility and access list.
The main part contains several zone sections, one for every direct and reverse
zone in which the server acts as the primary or a secondary name server. As usual, there is also a root zone section.
The root zone section defines the file with the root zone name servers.
Reverse local loop zone.
A direct zone for every domain and a reverse zone that the server processes as
a name server.
The final part containing the acl section, which defines an access control list of
name server IP addresses where zone transfers are allowed. By default, the
common-allow-transfer ACL is included in every zone section.
Note: If you perform change zone entries in the file manually, Panel will override them with changes made through the GUI.
Zone files
By default, zone files for domains are stored in the /var/named/run-root/var directory, as defined in the /var/named/run-root/etc/named.conf file. Each zone file has a name identical to the domain name. If you change the zone through the GUI, Panel rewrites the file.
Services Management 33
You can change a zone database by adding or deleting resource records as follows:
Using the Panel GUI. In this case, the Panel increases the Serial field value, which
means that the zone transfer operation should be performed to synchronize the zone content with all secondary name servers.
Manually editing the file. We do not recommend this approach, since Panel
completely rewrites the zone data from the psa database if any changes are made through the Panel GUI. Do not forget to increase the Serial field in this file. Otherwise, only this name server will know about the changes made.
Manually editing the psa database. To do this, perform the following steps:
First, you have to insert a corresponding record into the psa.dns_recs table.
mysql> insert into dns_recs (dom_id,type,host,val) values (2,'A','ws02.domain01.tst.','192.168.1.185');
Query OK, 1 row affected (0.00 sec)
After that, make the Panel reread the domain information from the psa database
in one of the following ways.
Through the command line:
# /usr/local/psa/admin/sbin/dnsmng update <domain_name>
Using the Panel GUI, switch the domain to slave and then back to the master
mode. In this case, you do not have to worry about the Serial field as the Panel increases its value while restoring the file.
Access Control Lists
You can restrict the name server to transferring name zones to only the list of explicitly assigned DNS servers. Do this by inserting the DNS server IP addresses into the misc table of the psa database with the following command:
mysql> insert into misc (param, val) values ('DNS_Allow_Transfer1', <dns server>);
for the first DNS server in the list.
mysql> insert into misc (param, val) values ('DNS_Allow_Transfer2', <dns server>);
for the second DNS server, etc.
To transfer the changes made in the database to the DNS configuration file, use the following command:
# /usr/local/psa/admin/sbin/dnsmng update <domain_name>
The command shown above adds DNS server IP addresses to the common-allow-
transfer ACL, which is included in all local name zones. Every domain can have some
additional IP addresses in its ACL. Secondary servers are added to the allow-transfer list of a domain by the Panel after adding the corresponding NS records to the domain name zone. In addition, the secondary server must be resolvable and accessible when it is added to the name zone.
34 Services Management
DNS logs
The domain name service writes errors log stored in the /var/log/messages file. The logrotate utility rotates this log on a daily, weekly, or monthly basis. Learn how to configure log rotation in the section Log Rotation (on page 125).
FTP
To provide an FTP service, Panel uses the ProFTPD FTP server. Panel includes the following two packages:
psa-proftpd which contains the main component.
psa-proftpd-xinetd which contains patches and configurations to work with xinetd.
FTP Startup
The ProFTPD is started by the xinetd every time the server receives an FTP request. In the case of authorized access, the FTP service is started on behalf of the user whose request is to be processed. For anonymous users, the service is started with the UID of the psaftp user.
FTP Users
The FTP server allows for document access of authenticated users that are listed in the
/etc/passwd and /etc/shadow files. The first one defines the user name, group
membership, home directory, and active access method. The second one stores password hash values. Let us look at FTP users created during the virtual hosting setup procedure. The following are some /etc/passwd lines defining FTP user parameters.
# grep ftp /etc/passwd ftp:x:14:50:FTP User:/var/ftp:/sbin/nologin psaftp:x:2524:2522:anonftp psa user:/:/bin/false ftpuser:x:10006:10001::/var/www/vhosts/domain.tst:/bin/false ftpuser55:x:10010:10001::/var/www/vhosts/domainXX.tst:/bin/false
The first two lines are default FTP users. The psaftp is the user on behalf of whom the FTP service is started when the Panel server receives an anonymous FTP request.
The last two lines define typical FTP users. The group ID 10001 refers to the psacln group that contains FTP users. The psacln is added to the /etc/ftpchroot file. For every
FTP user logged into the Panel, a “chroot” procedure is executed, which ensures the
user cannot see files owned by other users.
Panel stores all FTP user accounts in a single database; therefore, FTP users cannot have the same names even if they are created for different virtual hosts. Besides, since the FTP service cannot be name based, only one virtual host on each IP address can provide anonymous FTP access.
Services Management 35
FTP Configuration
The FTP server configuration parameters are stored in the /etc/proftpd.conf file. Here are some of the parameters. A sample of the proftpd.conf file is displayed below:
DefaultServer on <Global> DefaultRoot ~ psacln AllowOverwrite on </Global> DefaultTransferMode binary UseFtpUsers on
TimesGMT off SetEnv TZ :/etc/localtime # Port 21 is the standard FTP port. Port 21 # Umask 022 is a good standard umask to prevent new dirs and files # from being group and world writable. Umask 022
# To prevent DoS attacks, set the maximum number of child processes # to 30. If you need to allow more than 30 concurrent connections # at once, simply increase this value. Note that this ONLY works # in standalone mode, in inetd mode you should use an inetd server # that allows you to limit maximum number of processes per service # (such as xinetd) MaxInstances 30
#Following part of this config file were generate by PSA automatically #Any changes in this part will be overwritten by next manipulation #with Anonymous FTP feature in PSA control panel.
#Include directive should point to place where FTP Virtual Hosts configurations #preserved ScoreboardFile /var/run/proftpd/scoreboard # Primary log file mest be outside of system logrotate province TransferLog /usr/local/psa/var/log/xferlog #Change default group for new files and directories in vhosts dir to psacln <Directory /var/www/vhosts> GroupOwner psacln </Directory> # Enable PAM authentication AuthPAM on AuthPAMConfig proftpd IdentLookups off UseReverseDNS off AuthGroupFile /etc/group Include /etc/proftpd.include
36 Services Management
Each virtual host FTP configuration is stored in the /etc/proftpd.include file. The configurations consist of two sections:
The general section configures FTP for authorized users. It configures the
following:
Virtual server name to IP address binding.
Log file path.
Write permission.
Login access allowed only to the psacln group.
Below is a sample of the general section:
<VirtualHost 192.168.37.101> ServerName "ftp.swtrn.com" TransferLog /usr/local/psa/var/log/xferlog AllowOverwrite on <Limit LOGIN> Order allow, deny AllowGroup psacln Deny from all </Limit>
The Anonymous section configures FTP for anonymous users. It configures:
An alias for the psaftp user account.
anon_ftp as the home directory that is inside the domain directory opened for the
authorized domain user.
A log file for anonymous FTP access.
User and group for anonymous FTP access.
Login access and read-only rights for everyone Below is a sample of this section:
UserAlias anonymous psaftp <Anonymous /var/www/vhosts/domain.tst/anon_ftp> TransferLog /var/www/vhosts/domain.tst/statistics/logs/xferlog PathDenyFilter "^\.quota$" RequireValidShell off TransferRate RETR 0.000 User psaftp Group psaftp <Limit LOGIN> AllowAll </Limit> <Limit WRITE> DenyAll </Limit> <Directory incoming> UserOwner ftpuser Umask 022 002 <Limit STOR> DenyAll </Limit> <Limit WRITE> DenyAll
Services Management 37
</Limit> <Limit READ> DenyAll </Limit> <Limit MKD XMKD> DenyAll </Limit> </Directory> </Anonymous>
For more information on the ProFTPD configuration, please refer to the
www.proftpd.org.
FTP Logs and Statistics
For each domain, the ProFTPD service writes statistics for both anonymous and authorized access to log files located in the
/var/www/vhosts/<domain_name>/statistics/logs/ directory. Once a day, Panel processes
the logs with the statistics utility and separates the statistical data into two parts:
Anonymous access information stored in the statistics/anon_ftpstat subdirectory of
the virtual host directory.
Authorized access information stored in the statistics/ftpstat/subdirectory.
In addition, the statistics utility writes the statistical data to the psa database and calls the log rotation utility logrotate. For more information on statistics processing and log rotation, refer to the chapter Statistics and Logs (on page 122).
38 Services Management

Mail Service

In this section:
Restoring Mail Configuration ..............................................................................39
Installing Custom SSL Certificates for Qmail or Courier-IMAP Mail Servers .......40
Outgoing Mail from Exclusive IP Addresses .......................................................44
To provide a mail service, Parallels Plesk Panel supports two mail transfer agents:
Postfix and qmail.
Panel uses only one mail transfer agent at a time. You can check which of them is currently enabled on the following page: Server Administration Panel > Tools & Settings >
Services Management. You can also do this by running the mailmng utility located in the $PRODUCT_ROOT_D/admin/sbin/directory, where the $PRODUCT_ROOT_D is /usr/local/psa for RPM-based systems or /opt/psa on DEB-based systems:
./mailmng --features | grep SMTP_Server
By default, Panel for Linux uses the Postfix for sending and receiving mail through the SMTP and SMTPS protocols. You can switch to qmail by running the following command:
# /usr/local/psa/admin/sbin/autoinstaller --select-release-current -­install-component qmail
To switch to Postfix run the following command:
# /usr/local/psa/admin/sbin/autoinstaller --select-release-current -­install-component postfix
Both Postfix and qmail use the same root directory to store incoming mail. This directory is defined by the variable $PLESK_MAILNAMES_D in the /etc/psa/psa.conf configuration file. By default, it is /var/qmail/mailnames. Storing incoming mail in the same directory allows the messages remain available after switching between mail agents.
Unlike incoming mail, the mail queue is lost while switching between the mail agents. Therefore, before switching, we recommend you stop the SMTP service to prevent the acceptance of email and the delivery of all queued mail. To stop the SMTP service, run the following command:
# /usr/local/psa/admin/sbin/mailmng --stop-smtpd
To flush the queue, run the command:
for qmail: # kill -ALRM `pidof qmail-send`
for Postfix: # postqueue -f
Services Management 39

Restoring Mail Configuration

Sometimes, Parallels Plesk Panel mail server configuration becomes corrupt and it is necessary to restore it. The restoration is carried out by the internal mchk utility, which is intended for use by Parallels Plesk Panel. However, as the administrator, you can use it for restoring the Qmail and Courier-imap configuration when needed.
By default, mchk runs in the background mode. To execute it in the foreground, use the -v option. For example:
/usr/local/psa/admin/sbin/mchk -v
Note: You may not wish to restore SpamAssassin settings for mail accounts, as it requires Perl interpreter to be run. To speed up the restore process, use the --without-spam option.
40 Services Management
Installing Custom SSL Certificates for Qmail or Courier-
In this section:
Installing an SSL Certificate for Qmail ............................................................... 41
Installing SSL Certificates for the Courier-IMAP Mail Server ............................. 43
IMAP Mail Servers
To securely exchange mail data with Parallels Plesk Panel server, you may need to install custom SSL certificates on the Parallels Plesk Panel server. Specifically, SSL certificates can be installed for the Qmail mail transfer agent and the Courier-IMAP mail server that supports the IMAP and POP3 protocols.
To install custom SSL certificates, you need to download the certificates to the Parallels Plesk Panel server and then replace the installed default SSL certificates for Qmail and Courier-IMAP servers with the downloaded custom certificates.
This section describes procedures for installing custom SSL certificates for Qmail and Courier-IMAP servers.
Services Management 41
Installing an SSL Certificate for Qmail
To install a custom SSL certificate for Qmail on a Parallels Plesk Panel server:
1. Create a combined .pem certificate file.
To create a combined .pem certificate file, start your favorite text editor and paste the contents of each certificate file and the private key in the file in the following order:
a. The private key
b. The primary certificate
c. The intermediate certificate
d. The root certificate
Make sure that you include the begin and end tags of the key and each certificate including the dash lines. The resulting text should look like this:
-----BEGIN RSA PRIVATE KEY-----
..........
(Your Private Key here)
..........
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
..........
(Your Primary SSL certificate here)
..........
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
..........
(Your Intermediate certificate here)
..........
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
..........
(Your Root certificate here)
..........
-----END CERTIFICATE-----
2. Save the combined certificate file as plesk.pem.
3. Log in to a Parallels Plesk Panel server through SSH as a root user.
4. Download the combined certificate file plesk.pem.
42 Services Management
5. Make a backup copy of the existing default SSL certificate for Qmail.
For example for RedHat or Fedora operating systems, the SSL certificate file that you need to back up is var/qmail/control/servercert.pem.
Note: For other operating systems, the default certificate file location may be different.
6. Open the default certificate file /var/qmail/control/servercert.pem
using your favorite text editor, and replace the contents of the file with the contents of the combined certificate file plesk.pem.
7. Save and close the file.
8. To finish the certificate installation, restart Qmail.
Services Management 43
Installing SSL Certificates for the Courier-IMAP Mail Server
To install a custom SSL certificate for the Courier-IMAP (IMAP/POP3) mail
server on a Parallels Plesk Panel server:
1. Log in to a Parallels Plesk Panel server through SSH as a root user.
2. Download one or more SSL certificate files that you want to install.
Note: IMAP and POP3 each require separate certificate files, but both files can contain
the same certificate.
3. Make a backup copy of the existing default SSL certificate for the Courier­IMAP mail server.
For example for RedHat or Fedora operating systems, you need to back up the following default SSL certificate files:
/usr/share/courier-imap/imapd.pem - the certificate enables secure data
transfers through the IMAP protocol.
/usr/share/courier-imap/pop3d.pem - the certificate enables secure data
transfers through the POP3 protocol.
Note: For other operating systems, the default certificate file locations may be different.
4. Open a default certificate file using your favorite text editor and replace the
contents of the file, with the content of the SSL certificate file that you want to install.
For example, the content to be copied from a custom SSL certificate and pasted in lieu of a default certificate file body should look like this:
-----BEGIN CERTIFICATE-----
MIIB8TCCAZsCBEUpHKkwDQYJKoZIhvcNAQEEBQAwgYExCzAJBgNVBAYTAlJPMQww
............
............
eNpAIeF34UctLcHkZJGIK6b9Gktm
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
MIICXgIBAAKBgQDv6i/mxtS2B2PjShArtOAmdRoEcCWa/LH1GcrbW14zdbmIqrxb
..........
..........
faXRHcG37TkvglUZ3wgy6eKuyrDi5gkwV8WAuaoNct5j5w==
-----END RSA PRIVATE KEY-----
5. Save and close the file.
6. To finish the certificate installation, restart Courier-IMAP.
44 Services Management

Outgoing Mail from Exclusive IP Addresses

Operating system
Postfix version
CentOS 5
Postfix 2.8.4 packaged by Parallels
CentOS 6
Postfix 2.8.4 packaged by Parallels
RedHat Enterprise Linux 5
Postfix 2.8.4 packaged by Parallels
RedHat Enterprise Linux 6
Postfix 2.8.4 packaged by Parallels CloudLinux 5
Postfix 2.8.4 packaged by Parallels
CloudLinux 6
Postfix 2.8.4 packaged by Parallels
Ubuntu 10.04
Postfix 2.7
SuSE 11.3
Postfix 2.7
In earlier Panel versions, the outgoing mail of all customers was sent from a single IP address (defined by the mail server configuration). Thus, if one of the customers became blacklisted for sending spam, other customers were automatically blacklisted too since they used the same IP address. Also, if a customer had several IP addresses, and the address for outgoing mail did not match the address of the domain, the customer run a risk to be blacklisted as well.
In the current Panel version, the problem of domain and mail addresses is resolved, and Postfix mail server uses customers' IP addresses for sending mail if possible. This targets all outgoing mail of the Panel mail server sent by PHP mail(), sendmail, an SMTP script or client. However, if the following conditions are true, your system may send mail from different IP addresses:
You have Postfix 2.7 Panel is configured to support IPv6 A subscription has only a single IPv4 or IPv6,
The outgoing mail for such subscriptions can be equally sent from either the customer's IP address or the server-defined IP address of the opposite type (IPv6 for IPv4 and vice versa). This server-defined IP address is specified in the mail server configuration.
Another part of this feature is the sender's address validation: The system validates the MAIL FROM header for authenticated users and corrects the header if needed. However, if the mail is sent without authentication, say, from 127.0.0.1, through the local sendmail, or a sender is in the white list, the system trusts the MAIL FROM header.
Requirements
This feature is supported on all operating systems which have Postfix 2.7 or later. They are as follows:
Services Management 45
SuSE 11.4
Postfix 2.7
Debian 6
Postfix 2.7
In this section:
Configuring a Mailing List That Only Members are Allowed to Post to ............... 46
Importing a List of E-mail Addresses into a Mailing List..................................... 46
If you independently install Postfix, run the following command to turn on the feature:
/usr/local/psa/admin/sbin/mchk
Read more about the utility in http://kb.parallels.com/944.

Mailing Lists Management System

Mailman is a GNU Mailing List Management System that provides a web-based mail list
administration interface. It can work with almost all known mail transfer agents.
Mailman Directory Structure
Root directory:
/usr/lib/mailman Executable Python scripts:
/usr/lib/mailman/bin/mailmanctl
/usr/lib/mailman/bin/qrunner Startup script:
/etc/init.d/mailman with status|stop|start|restart options.
Note that /etc/init.d may be /etc/rc.d/init.d on some systems.
Configuration:
usr/lib/mailman/Mailman/Defaults.py
usr/lib/mailman/Mailman/mm_cfg.py is changed by the Panel when working with mail lists.
Mail lists:
/var/lib/mailman/lists/
Documentation:
/usr/share/doc/mailman-2.1.x/
46 Services Management

Configuring a Mailing List That Only Members are Allowed to Post to

By default, when you create a mailing list, everyone may send correspondence to this list. If you need to configure a mailing list that only members are allowed to send mail to, you can do this through the WEB Mailman interface.
To configure a mailing list that only members are allowed to post to:
1. Log in to the WEB Mailman interface as the list administrator.
2. Enable the Restrict posting privilege to list members option.
Note: By default a mailing list is created with the Posts must be approved by an administrator
option enabled. That means all messages must be approved by the moderator before they are posted to the list. Therefore, if this option is disabled and unwanted mail is posted to the list, you can re-enable it and moderate incoming messages.
For more information, please see Mailman documentation at:
http://www.gnu.org/software/mailman/docs.html.

Importing a List of E-mail Addresses into a Mailing List

If you need to import a number of e-mail addresses into a mailing list, adding them individually can take a long time. To automate this task you can use Parallels Plesk Panel creation utilities. To add several e-mail addresses to the mailing list, run the following command:
# /usr/local/psa/bin/maillist.sh --update <mailing list> -members add:<e-mail 1>[,<e-mail 2>,...,<e-mail N>]

Web Apps

Multiple Web Apps in a Single Directory

Since Panel 10.4, when a site employs a number of various web apps, a site administrator may apply the following site structure:
Install a number of apps to the same directory. More specifically, install one app into a
subdirectory of another.
Use the same document root for a subdomain and a web app.
For example, you may install an online store app to the httpdocs directory of your domain (say, example.com), create a subdomain (say, support.example.com) in the httpdocs/support, and install a help desk system there.
Services Management 47
All earlier Panel versions (before 10.4) prohibited such scenarios as sometimes (in very rare cases), the installation of two web apps into one directory may lead to the improper functioning of one of them. If you want to return this restriction back, add the following lines into $PRODUCT_ROOT/admin/conf/panel.ini:
[aps] unsafePaths=false

Hiding Commercial Apps

You can hide commercial web applications by default, so that your customers are able to install only free applications. To do this, add the following lines into $PRODUCT_ROOT/admin/conf/panel.ini:
[aps] commercialAppsEnabled = false
48 Services Management

Spam Protection

SpamAssassin is a rule-based mail filter that identifies spam. It uses a wide range of heuristic
tests on mail headers and body text to identify spam.
SpamAssassin filtering is configured on two levels:
Server-level configuration is done by Panel administrator. Mail directory-level configuration is done by users for specific mail directories.
At the server level, you (as a Panel administrator) can enable or disable any of these two types of filters. Thus, there are four possible situations:
No filtering is applied, when spamd daemon is not running:
both filters are disabled by the Parallels Plesk Panel administrator.
the personal filter is disabled at the mail directory level.
Filtering is applied at the server level only. Filtering is applied at the mail box level only. Filtering is applied at both levels.
When both filters are enabled for a specific mail name, a combined filter is created for the corresponding mail directory. When processing messages, SpamAssassin calculates the number of hits according to its internal rules. A message is considered to be spam if the number of hits exceeds the established threshold, which is set to 7 by default. You can change the threshold in Panel. White and Black lists can be considered special rules, which assign constant hit rates to messages conforming to mail address patterns in these lists:
If the message source address conforms to the Black list, the message gets +100 hits by
default.
If the message source address conforms to the White list, the message gets -100 hits by
default.
Sometimes, a message matches both Black and White lists. In that case, it has +100-100=0 hits.
If the message destination address is included in the server-wide ignore list, then all messages to this address will go directly to the addressed mail directory.
At the server level, you can configure SpamAssassin to mark messages with a special string if they are recognized as containing spam. At the mailbox level, you can make SpamAssassin delete or mark the message if it is considered as spam.
Starting from Panel 9.x, the maximum message size to filter is hardcoded in the spam handler and set to 256KB. This value provides normal server loading. Since the
SpamAssassin service consists of perl modules, they may result in a heavy server load when
processing long messages.
You can get more information on SpamAssassin at spamassassin.apache.org
Services Management 49
In this section:
Configuring SpamAssassin ............................................................................... 49
Training SpamAssassin to Work with All Mail Accounts on the Server .............. 50
Fighting Spam on a Qmail Mail Server .............................................................. 51

Configuring SpamAssassin

The SpamAssassin configuration is stored in the spamfilter and spamfilter_preferences tables of the psa database. You can manage it with the $PRODUCT_ROOT_D/admin/bin/spammng utility. It displays help if started without any options.
Server-wide SpamAssassin settings are stored in the following files:
The /usr/share/spamassasin/*.cf files contain configuration details, e.g. White list and Black
list scores are assigned in the 50_scores.cf configuration file.
The /etc/mail/spamassassin/local.cf stores server-wide filter settings.
When Panel works with virtual mail users (not real system users with UIDs) spamd is executed with keys showing where to find the configuration files of virtual users:
-x --virtual-config-dir={QMAIL_MAILNAMES_D}/%d/%l User settings are stored in the
following files:
/var/qmail/mailnames/<domain>/<mailname>/.spamassassin/user_prefs file defines
SpamAssassin actions.
/var/qmail/mailnames/<domain>/<mailname>/.qmail defines how message flow reaches
SpamAssassin daemons.
If the message destination address is included in the server-wide ignore list then all messages to this address will go directly to the addressed mail directory. For example, if you include admin@domain01.tst in this list, then the .qmail file will look like this:
# cat /var/qmail/mailnames/domainXX.tst/mailuser/.qmail | /usr/local/psa/bin/psa-spamc accept | true | /usr/bin/deliverquota ./Maildir
If SpamAssassin filtering is allowed then the following command allows the mail to go through the spam filter first and then to the mailbox added to this file:
| spamc -f -u admin@domainXX.tst|maildir ./Maildir/
You can find examples of spam-like and no-spam messages in:
/usr/share/doc/spamassassin-3.2.x/sample-nonspam.txt/usr/share/doc/spamassassin-3.2.x/sample-spam.txt
50 Services Management

Training SpamAssassin to Work with All Mail Accounts on the Server

You can manually train SpamAssassin to work with all mail accounts on the server from the command line.
To train SpamAssassin to work with all mail names on the server:
1. Store spam and ham (non-spam) messages in two different folders, for example spam_mails and ham_mails.
2. Train SpamAssassin to work with one mailbox using the messages from these folders:
# cd /path/to/spam_mail/ # for message in * ; do /usr/local/psa/admin/sbin/spammng --bayes -­mailname=mailname@domain.com --spam=$message ; done # cd /path/to/ham_mail/ # for message in * ; do /usr/local/psa/admin/sbin/spammng --bayes -­mailname=mailname@domain.com --ham=$message ; done
3. Repeat this command for every mailbox on the server or just copy bayes bases (./domain.com/mailname/.spamassassin/bayes_*) from this mailbox to other mailboxes with the following command:
# find /var/qmail/mailnames/ -mindepth 2 -maxdepth 2 -type d -exec /bin/cp
-f /var/qmail/mailnames/domain.com/mailname/.spamassassin/bayes_*
{}/.spamassassin/ \;
where domain.com and mailname should be replaced with the real domain name and mail name.
Services Management 51

Fighting Spam on a Qmail Mail Server

When unsolicited e-mails, or spam, are simultaneously sent indiscriminately to multiple mail boxes on your server, there may be too many messages in the queue. Then the server can become overloaded with spam and mail is delivered slowly.
To get rid of spam on your Qmail mail server:
1. Make sure that all domains have the Mail to nonexistent user option set to Reject.
To change this option's value for a domain, open it in the Control Panel, go to the Mail tab and click Change Settings.
2. Make sure that there are no untrusted IP addresses or networks in the white list.
To do this, go to Home > Mail Server Settings > White List tab. To remove untrusted IP addresses or networks, select them in the list and click Remove Selected.
3. Check how many messages there are in the Qmail queue with:
# /var/qmail/bin/qmail-qstat
messages in queue: 27645 messages in queue but not yet preprocessed: 82
If there are too many messages in the queue, try to find out where the spam is coming from. If the mail is being sent by an authorized user, but not from a PHP script, you can find out which user sent most of the messages with the following command:
# cat /usr/local/psa/var/log/maillog |grep -I smtp_auth |grep -I user |awk '{print $11}' |sort |uniq -c |sort -n
Note that the SMTP authorization option should be enabled on the server to see these records. The path to maillog may be different depending on the OS you use.
4. Use the qmail-qread utility to read the messages headers:
# /var/qmail/bin/qmail-qread
18 Jul 2005 15:03:07 GMT #2996948 9073 <user@domain.com> bouncing done remote user1@domain1.com done remote user2@domain2.com done remote user3@domain3.com
....
The qmail-qread utility shows message senders and recipients. If a message has too many recipients, then it is probably spam.
5. Try to find the message in the queue by it's ID (for example, the message ID is #1234567):
# find /var/qmail/queue/mess/ -name 1234567
6. Look at the message and find the last Received line. This shows where the message was initially sent from.
52 Services Management
If you find something like:
Received: (qmail 19514 invoked by uid 12345); 10 Sep 2008 17:48:22 +0700
it means that this message was sent via a CGI script by user with UID 12345. Use this UID to find a corresponding domain:
# grep 12345 /etc/passwd
Received lines like:
Received: (qmail 19622 invoked from network); 10 Sep 2008 17:52:36 +0700 Received: from external_domain.com (192.168.0.1)
means that the message was accepted for delivery via SMTP and the sender is an authorized mail user.
If the Received line contains an UID of an apache user (for example invoked by
uid 48), it means that the spam was sent via an PHP script. In this case you can try
to find the spammer using information from the spam e-mails (from/to addresses, subjects, etc). But it is usually hard to find the spam source in this case. If you are sure that a script is sending spam at the current moment (for example, because the queue is growing very fast), you can use this little script to find out what PHP scripts are running in real-time:
# lsof +r 1 -p `ps axww | grep httpd | grep -v grep | awk ' { if(!str) { str=$1 } else { str=str","$1}}END{print str}'` | grep vhosts | grep php
To try to find out from what folder the PHP script that is sending mail was run, create /var/qmail/bin/sendmail-wrapper script with the following content:
#!/bin/sh (echo X-Additional-Header: $PWD ;cat) | tee -a /var/tmp/mail.send|/var/qmail/bin/sendmail-qmail "$@"
Note, the paths can slightly differ depending on your OS and Parallels Plesk Panel version.
Create a log file /var/tmp/mail.send and grant it a+rw rights, make the wrapper executable, rename old sendmail and link it to the new wrapper:
# touch /var/tmp/mail.send # chmod a+rw /var/tmp/mail.send # chmod a+x /var/qmail/bin/sendmail-wrapper # mv /var/qmail/bin/sendmail /var/qmail/bin/sendmail-qmail # ln -s /var/qmail/bin/sendmail-wrapper /var/qmail/bin/sendmail
Wait for about an hour and revert sendmail back:
# rm -f /var/qmail/bin/sendmail # ln -s /var/qmail/bin/sendmail-qmail /var/qmail/bin/sendmail
Examine the /var/tmp/mail.send file. There should be lines starting with X­Additional-Header pointing to domain folders where the script that sends the mail
is located.
You can see all the folders from which mail PHP scripts were run by using the following command:
Services Management 53
# grep X-Additional /var/tmp/mail.send | grep `cat
In this section:
Parallels Premium Antivirus ............................................................................... 54
Kaspersky Antivirus ........................................................................................... 56
/etc/psa/psa.conf | grep HTTPD_VHOSTS_D | sed -e 's/HTTPD_VHOSTS_D//' `
If you see no output from the command above, it means that no mail was sent using the PHP mail() function from the Parallels Plesk Panel virtual hosts directory.

Antivirus Support

Parallels Plesk Panel for Linux supports the following antivirus software:
Parallels Premium Antivirus based on Dr.Web.  Kaspersky Antivirus.
Both these solutions provide you with real-time mail traffic scanning and malware protection for customers. In this section you will find detailed information on these antivirus solutions.
54 Services Management

Parallels Premium Antivirus

Parallels Premium Antivirus is shipped with Panel in the form of RPM packages.
Directory Structure
Root directory:
/opt/drweb/ Configuration files:
/etc/drweb/ is a directory with various configuration files.  /etc/drweb/drweb32.ini is the default configuration file for drwebd engine.  /etc/drweb/drweb_qmail.conf is the configuration file for the qmail-queue filter.  /etc/drweb/users.conf stores the configuration for every mail name for which antivirus is
enabled.
Virus databases:
/var/drweb/bases/*vdb Quarantine directory:
/var/drweb/infected/ Log file:
/var/drweb/log/drwebd.log
Managing the Antivirus
The Dr.Web service is a standalone drwebd daemon (also called engine), which is started from the /etc/init.d/drwebd script. You can also stop and start it again with the following command:
# /etc/init.d/psa stopall # /etc/init.d/psa start
Note: these commands stop and start other Panel services: DNS server, mail server, and so on
You can also manage it within the Services Management page in the Server Administration Panel.
The interaction with drwebd is established through the Dr.Web client. It can change antivirus parameters and start checking files. The client displays a full list of its attributes if run without attributes. Also, it can extract detailed operational information from the engine. The following command gives information about the Dr.Web version and virus database.
# /opt/drweb/drwebdc -sv -sb
By default, the virus databases are updated every 30 minutes by means of the cron task:
/opt/drweb/update/update.pl >dev/null 2>&1
Services Management 55
Filtering Mail
Dr.Web substitutes the native qmail-queue filter used for transferring incoming messages to the qmail queue with its own utility. The utility's configuration settings are stored in the
/etc/drweb/drweb_handler.conf file.
Dr.Web filtering is activated on the mail name level. If enabled it can check incoming, outgoing or both kinds of messages. The information is stored in the /etc/drweb/users.conf file. The following is an example of three mail names with different Dr.Web configurations:
# grep domain01 /etc/drweb/users.conf allow any regex ^admin@domain01.tst$ allow to regex ^user01@domain.tst$ allow from regex ^user02@domain.tst$
In the above configuration, Dr.Web will check viruses in:
Incoming and outgoing messages for admin@domain01.tst Incoming messages for user01@domain01.tst Outgoing messages for user02@domain01.tst
56 Services Management

Kaspersky Antivirus

Kaspersky Antivirus is a module that scans incoming and outgoing mail traffic on your server,
and removes malicious and potentially dangerous code from e-mail messages. In order to use Kaspersky Antivirus with your Parallels Plesk Panel server, you need to install the Kaspersky Antivirus module, then purchase and install a license key.
Kaspersky Antivirus is distributed as an RPM package.
Kaspersky Antivirus Structure
Kaspersky Antivirus resides in the following directories in Panel.
/opt/kav/5.5/kav4mailservers - the main directory.  /etc/kav/5.5/kav4mailservers/kav4mailservers.conf - a configuration file that contains
parameters as key=value pairs grouped by sections. They define the operation of all Kaspersky Antivirus components. All configuration file parameters are grouped into sections, each of them corresponding to a particular component of the product.
/var/db/kav/5.5/kav4mailservers/bases - a path to the anti-virus database directory.  /var/db/kav/5.5/kav4mailservers/licenses - a path to the license keys directory.
Incoming and outgoing mail messages are processed like this:
1. The stream of mail messages comes in from other servers or mail clients via the SMTP protocol.
2. The mail system receives the mail traffic and passes it to Kaspersky Antivirus for scanning.
3. The application processes the mail traffic according to the specified settings, and returns it to the mail system along with an additional set of notifications.
4. The mail system routes the mail traffic to its destination.
This chapter discusses tasks that administrators may need to perform on an existing
In this chapter:
Managing Panel Objects Through the Command Line ...................................... 57
Executing Custom Scripts on Panel Events ....................................................... 58
Changing IP Addresses ..................................................................................... 58
Changing Paths to Services .............................................................................. 59
Restarting Panel ................................................................................................ 60
Managing Services from the Command Line and Viewing Service Logs ........... 60
C H A P T E R 4

System Maintenance

Panel installation. In particular, the chapter provides overviews on how to manage Panel through the command line and execute scripts or binaries on certain Panel events. In addition, you will learn how to adjust Panel settings to fit a new network environment or server configuration, and restart Panel to apply new settings.

Managing Panel Objects Through the Command Line

Parallels Plesk Panel Command Line Interface (CLI) is designed for integrating Panel with third-party applications. Panel administrators can also use it to create, manage, and delete customer and domain accounts, and other Panel objects from the command line. CLI utilities require administrative permissions on Panel server to run.
The utilities reside in the following directories:
On RPM-based systems: /usr/local/psa/bin
On DEB-based systems: /opt/psa/bin
Upon successful execution, utilities return the 0 code. If an error occurs, utilities return code 1 and display the error details.
To learn more about Panel command line utilities, refer to Panel 10.4 Command Line Reference at http://download1.parallels.net/Plesk/PP10/10.4.0/Doc/en-US/online/plesk-
unix-cli/.
58 System Maintenance

Executing Custom Scripts on Panel Events

Parallels Plesk Panel provides a mechanism that allows administrators to track specific Panel events and make Panel execute custom scripts when these events occur. The events include operations that Panel users perform on accounts, subscriptions, websites, service plans, and various Panel settings. For example, you can save each added IP address to a log file or perform other routine operations.
To learn how to track Panel events and set up execution of commands or custom scripts, refer to Parallels Plesk Panel Administrator's Guide, chapter Using Event Tracking Mechanism available at http://download1.parallels.com/Plesk/PP10/10.4.0/Doc/en-US/online/plesk-
administrator-guide/59205.htm.

Changing IP Addresses

During the lifetime of a Parallels Plesk Panel server, you may need to change the IP addresses employed by Panel. Two typical cases when IP addresses may need to be changed are the following:
Reorganization of the server IP pool. Say, to substitute one IP address with another. Relocation of Panel to another server. Change all addresses used by Panel (including the
one on which Panel resides) to those on the new server.
Every time the change happens, you should reconfigure all related system services. To help you do this promptly, we offer the reconfigurator command line utility located in the following directory:
on RPM-based systems:/usr/local/psa/bin.
on DEB-based systems:/opt/psa/bin.
The reconfigurator replaces IP addresses and modifies Panel and services configuration to make the system work properly after the replacement. To do this, the utility requires a mapping file, that includes instructions on what changes to make. Each line of the file should describe a single change. For example, the following line instructs Panel to change the IP address 192.168.50.60 to 192.168.50.61:
eth0:192.168.50.60 255.255.255.0 -> eth0:192.168.50.61 255.255.255.0
The utility also helps you with creation of the mapping file. If you call the utility with a new file name as an option, it will create the file and write all available IP addresses to it. The IP addresses in the file are mapped to themselves. If you want to perform a change, modify the change instruction for a certain IP address.
When editing the mapping file, consider the following:
A replacement IP address must not exist in the Panel IP pool before changing; however,
it may be in the server IP pool. To make sure the IP is not in the Panel IP pool, go to
Server Administration Panel > Tools & Settings > IP Addresses and remove the IP if necessary.
System Maintenance 59
If a replacement IP address does not exist in the server IP pool, the utility adds it to both
Panel and server IP pools.
To change IP addresses used by Panel:
1. Generate a mapping file with current Panel IP addresses by running the command:
./reconfigurator <ip_map_file_name>
2. Edit the file as described above and save it.
3. Reconfigure Panel and its services by running the following command one
more time:
./reconfigurator <ip_map_file_name>

Changing Paths to Services

Parallels Plesk Panel uses various external components, for example, Apache web server, mail service, antivirus, and so on. When interacting with these components, Panel gets the information on their locations from the configuration file /etc/psa/psa.conf.
Panel configuration file provides an easy way of reconfiguring Panel if a service is installed into another directory or migrated from the current partition to another. Note that you can only modify paths present in this file; other paths are hard-coded in Panel components.
Each line of psa.conf has the following format:
<variable_name> <value>
A sample part of the psa.conf file is displayed below. To change a path to a service, utility, or package, specify the new path as a value of a corresponding variable.
# Plesk tree PRODUCT_ROOT_D /usr/local/psa # Directory of SysV-like Plesk initscripts PRODUCT_RC_D /etc/init.d # Directory for config files PRODUCT_ETC_D /usr/local/psa/etc # Directory for service utilities PLESK_LIBEXEC_DIR /usr/lib/plesk-9.0 # Virtual hosts directory HTTPD_VHOSTS_D /var/www/vhosts # Apache configuration files directory HTTPD_CONF_D /etc/httpd/conf # Apache include files directory HTTPD_INCLUDE_D /etc/httpd/conf.d # Apache binary HTTPD_BIN /usr/sbin/httpd #Apache log files directory HTTPD_LOG_D /var/log/httpd #apache startup script HTTPD_SERVICE httpd # Qmail directory QMAIL_ROOT_D /var/qmail
60 System Maintenance
Important: Be very careful when changing the contents of psa.conf. Mistakes in paths specified in this file may lead to Panel malfunctioning.

Restarting Panel

Ifyou experience problems with Parallels Plesk Panel, for example, malfunctioning of a service, you can try to resolve them by restarting Panel or the administrative web server sw- cp-server. Also, a restart is necessary to apply configuration changes that cannot be made while Panel is running.
To restart Parallels Plesk Panel, run the following command:
/etc/init.d/psa restart
To restart sw-cp-server, run the following command:
/etc/init.d/sw-cp-server restart

Managing Services from the Command Line and Viewing Service Logs

This section describes how to stop, start, and restart services managed by Panel, and access their logs and configuration files.
Parallels Plesk Panel web interface
To start the service through the command line:
/etc/init.d/psa start
To stop the service through the command line:
/etc/init.d/psa stop
To restart the service through the command line:
/etc/init.d/psa restart
Panel log files are located in the following directories:
Error Log: /var/log/sw-cp-server/error_log
Access log: /usr/local/psa/admin/logs/httpsd_access_log Panel configuration files are the following:
php: $PRODUCT_ROOT_D/admin/conf/php.ini
www: /etc/sw-cp-server/applications.d/plesk.conf
System Maintenance 61
Web Presence Builder
Log files are located in:
Error log: /var/log/httpd/sitebuilder_error.log
Logs: /usr/local/sitebuilder/tmp/ Configuration files are accessible at:
/usr/local/sitebuilder/config /usr/local/sitebuilder/etc/php.ini
SSO
Log files are located in:
Error log: /var/log/sw-cp-server/error_log
SSO log: /var/log/sso/sso.log Configuration files are accessible at:
/etc/sw-cp-server/applications.d/sso-cpserver.conf
/etc/sso/sso_config.ini
phpMyAdmin
The error log is located in:
/var/log/sw-cp-server/error_log
The configuration file is accessible at:
/usr/local/psa/admin/htdocs/domains/databases/phpMyAdmin/libraries/c onfig.default.php
phpPGAdmin
The error log is located in:
/var/log/sw-cp-server/error_log
The configuration file is accessible at:
/usr/local/psa/admin/htdocs/domains/databases/phpPgAdmin/conf/config .inc.php
62 System Maintenance
DNS / Named / BIND
To start the service through the command line:
/etc/init.d/named start
To stop the service through the command line:
/etc/init.d/named stop
To restart the service through the command line:
/etc/init.d/named restart
Log files are located in:
/var/log/messages
The configuration file is accessible at:
/etc/named.conf
FTP (ProFTPD)
Log files are located in:
/usr/local/psa/var/log/xferlog
Configuration files are accessible at:
/etc/xinetd.d/ftp_psa
/etc/proftpd.conf /etc/proftpd.include
Courier-IMAP
To start the service through the command line:
/etc/init.d/courier-imap start
To stop the service through the command line:
/etc/init.d/courier-imap stop
To restart the service through the command line:
/etc/init.d/courier-imap restart
Log files are located in:
/usr/local/psa/var/log/maillog
Configuration files are accessible at:
/etc/courier-imap/imapd /etc/courier-imap/imapd-ssl /etc/courier-imap/pop3d /etc/courier-imap/pop3d-ssl
System Maintenance 63
QMail
To start the service through the command line:
/etc/init.d/qmail start
To stop the service through the command line:
/etc/init.d/qmail stop
To restart the service through the command line:
/etc/init.d/qmail restart
Log files are located in:
/usr/local/psa/var/log/maillog
Configuration files are accessible at:
/etc/xinetd.d/smtp_psa
/etc/xinetd.d/smtps_psa /etc/xinetd.d/submission_psa /etc/inetd.conf (Debians)
/var/qmail/control/
Postfix
To start the service through the command line:
/etc/init.d/postfix start
To stop the service through the command line:
/etc/init.d/postfix stop
To restart the service through the command line:
/etc/init.d/postfix restart
Log files are located in:
/usr/local/psa/var/log/maillog
Configuration files are accessible at:
/etc/postfix/
SpamAssassin
To start the service through the command line:
/etc/init.d/psa-spamassassin start
To stop the service through the command line:
/etc/init.d/psa-spamassassin stop
To restart the service through the command line:
/etc/init.d/psa-spamassassin restart
64 System Maintenance
Log files are located in:
/usr/local/psa/var/log/maillog
Configuration files are accessible at:
/etc/mail/spamassassin/ /etc/mail/spamassassin/local.cf /var/qmail/mailnames/%d/%l/.spamassassin
Dr.Web antivirus
To start the service through the command line:
/etc/init.d/drwebd start
To stop the service through the command line:
/etc/init.d/drwebd stop
To restart the service through the command line:
/etc/init.d/drwebd restart
Log files are located in:
/usr/local/psa/var/log/maillog
Configuration files are accessible at:
/etc/drweb/
Kaspersky antivirus
To start the service through the command line:
/etc/init.d/aveserver start
To stop the service through the command line:
/etc/init.d/aveserver stop
To restart the service through the command line:
/etc/init.d/aveserver restart
Log files are located in:
/usr/local/psa/var/log/maillog
/var/log/kav/5.5/kav4mailservers/aveserver.log /var/log/kav/5.5/kav4mailservers/smtpscanner.log /var/log/kav/5.5/kav4mailservers/avstats.log /var/log/kav/5.5/kav4mailservers/kavscanner.log
/var/log/kav/5.5/kav4mailservers/kavupdater.log Configuration files are accessible at:
/etc/kav/5.5/kav4mailservers/
System Maintenance 65
Tomcat
To start the service through the command line:
/etc/init.d/tomcat5 start
To stop the service through the command line:
/etc/init.d/tomcat5 stop
To restart the service through the command line:
/etc/init.d/tomcat5 restart
Log files are located in:
/var/log/tomcat5/
Configuration files are accessible at:
/usr/share/tomcat5/conf/
MySQL
To start the service through the command line:
/etc/init.d/mysqld start
To stop the service through the command line:
/etc/init.d/mysqld stop
To restart the service through the command line:
/etc/init.d/mysqld restart
Log file is located in:
/var/log/mysqld.log
The configuration file is accessible at:
/etc/my.cnf
Postgresql
To start the service through the command line:
/etc/init.d/postgresql start
To stop the service through the command line:
/etc/init.d/postgresql stop
To restart the service through the command line:
/etc/init.d/postgresql restart
Startup log is located in:
/var/lib/pgsql/pgstartup.log
The configuration file is accessible at:
/var/lib/pgsql/data/postgresql.conf
66 System Maintenance
xinetd
To start the service through the command line:
/etc/init.d/xinetd start
To stop the service through the command line:
/etc/init.d/xinetd stop
To restart the service through the command line:
/etc/init.d/xinetd restart
Log files are located in:
/var/log/messages/
The configuration file is accessible at:
/etc/xinetd.conf
Watchdog (monit)
To start the service through the command line:
/usr/local/psa/admin/bin/modules/watchdog/wd --start
To stop the service through the command line:
/usr/local/psa/admin/bin/modules/watchdog/wd --stop
To restart the service through the command line:
/usr/local/psa/admin/bin/modules/watchdog/wd --restart
Log files are located in:
/usr/local/psa/var/modules/watchdog/log/wdcollect.log
/usr/local/psa/var/modules/watchdog/log/monit.log Configuration files are
accessible at:
/usr/local/psa/etc/modules/watchdog/monitrc /usr/local/psa/etc/modules/watchdog/wdcollect.inc.php
Watchdog (rkhunter)
Log is located in:
/var/log/rkhunter.log
The configuration file is accessible at:
/usr/local/psa/etc/modules/watchdog/rkhunter.conf
System Maintenance 67
Apache
To start the service through the command line:
/etc/init.d/httpd start
To stop the service through the command line:
/etc/init.d/httpd stop
To restart the service through the command line:
/etc/init.d/httpd restart
Log files are located in:
/var/log/httpd/
/var/www/vhosts/<domain_name>/statistics/logs/ Configuration files are
accessible at:
/etc/httpd/conf/httpd.conf
/etc/httpd/conf.d/
/var/www/vhosts/<domain_name>/conf/httpd.include
Mailman
To start the service through the command line:
/etc/init.d/mailman start
To stop the service through the command line:
/etc/init.d/mailman stop
To restart the service through the command line:
/etc/init.d/mailman restart
Log files are located in:
/var/log/mailman/
Configuration files are accessible at:
/etc/httpd/conf.d/mailman.conf
/usr/lib/mailman/Mailman/mm_cfg.py /etc/mailman/sitelist.cfg
AWstats
To start the service through the command line:
/usr/local/psa/bin/sw-engine-pleskrun /usr/local/psa/admin/plib/DailyMaintainance/script.php
Configuration files are accessible at:
/usr/local/psa/etc/awstats/
68 System Maintenance
Webalizer:
To start the service through the command line:
/usr/local/psa/bin/sw-engine-pleskrun /usr/local/psa/admin/plib/DailyMaintainance/script.php
Configuration files are accessible at:
/var/www/vhosts/<domain_name>/conf/webalizer.conf
Backup Manager
Backup logs are located in:
/usr/local/psa/PMM/sessions/<session>/psadump.log
/usr/local/psa/PMM/sessions/<session>/migration.log /usr/local/psa/PMM/logs/migration.log
/usr/local/psa/PMM/logs/pmmcli.log Restore logs are located in:
/usr/local/psa/PMM/rsessions/<session>/conflicts.log /usr/local/psa/PMM/rsessions/<session>/migration.log /usr/local/psa/PMM/logs/migration.log
/usr/local/psa/PMM/logs/pmmcli.log The configuration file is accessible at:
/etc/psa/psa.conf
Plesk Migration Manager
Migration logs are located in:
/usr/local/psa/PMM/msessions/<session>/migration.log
/usr/local/psa/PMM/rsessions/<session>/migration.log /usr/local/psa/PMM/rsessions/<session>/conflicts.log /usr/local/psa/PMM/logs/migration.log
/usr/local/psa/PMM/logs/pmmcli.log /usr/local/psa/PMM/logs/migration_handler.log
Horde
Log is located in:
/var/log/psa-horde/psa-horde.log
Configuration files are accessible at:
Apache configuration
/etc/httpd/conf.d/zzz_horde_vhost.conf
/etc/psa-webmail/horde/conf.d/
Horde configuration:
/etc/psa-webmail/horde/
System Maintenance 69
Atmail
Log files are located in:
/var/log/atmail/
Configuration files are accessible at:
Apache configuration
/etc/httpd/conf.d/zzz_atmail_vhost.conf
/etc/psa-webmail/atmail/conf.d/
Atmail configuration:
/etc/psa-webmail/atmail/atmail.conf
/var/www/atmail/libs/Atmail/Config.php
psa-logrotate
To start the service through the command line:
/usr/local/psa/bin/sw-engine-pleskrun /usr/local/psa/admin/plib/DailyMaintainance/script.php
Configuration files are accessible at:
/usr/local/psa/etc/logrotate.conf /usr/local/psa/etc/logrotate.d/
Samba
To start the service through the command line:
/etc/init.d/smb start
To stop the service through the command line:
/etc/init.d/smb stop
To restart the service through the command line:
/etc/init.d/smb restart
Log files are located in:
/var/log/samba/
Configuration files are accessible at:
/etc/samba/smb.conf /etc/samba/smb.conf.include
70 System Maintenance
psa-firewall
To start the service through the command line:
/etc/init.d/psa-firewall start
To stop the service through the command line:
/etc/init.d/psa-firewall stop
To restart the service through the command line:
/etc/init.d/psa-firewall restart
Configuration files are accessible at:
/usr/local/psa/var/modules/firewall/firewall-active.sh /usr/local/psa/var/modules/firewall/firewall-emergency.sh
/usr/local/psa/var/modules/firewall/firewall-new.sh
psa-firewall (IP forwarding)
To start the service through the command line:
/etc/init.d/psa-firewall-forward start
To stop the service through the command line:
/etc/init.d/psa-firewall-forward stop
To restart the service through the command line:
/etc/init.d/psa-firewall-forward restart
Configuration files are accessible at:
/usr/local/psa/var/modules/firewall/ip_forward.active /usr/local/psa/var/modules/firewall/ip_forward.saved
psa-vpn
To start the service through the command line:
/etc/init.d/smb start
To stop the service through the command line:
/etc/init.d/smb stop
To restart the service through the command line:
/etc/init.d/smb restart
The configuration file is accessible at:
/usr/local/psa/var/modules/vpn/openvpn.conf
This chapter describes how to back up and restore data by means of the command-line
In this chapter:
Backing Up Data ............................................................................................... 72
Restoring Data .................................................................................................. 91
Migrating Data ................................................................................................... 121
C H A P T E R 5

Backing Up, Restoring, and Migrating Data

utilities pleskbackup and pleskrestore, and introduces the tools for migrating hosted data between servers.
Backing up by means of the pleskbackup utility is done by issuing a command that specifies the objects to be backed up. The utility creates a backup archive containing settings and content. You can then perform a full or a selective restoration of data, and specify how to resolve possible conflicts that might occur.
72 Backing Up, Restoring, and Migrating Data

Backing Up Data

In this section:
Backup Objects: Hierarchy and Volume ............................................................ 73
Specifying Data for Backing Up ......................................................................... 76
Defining Properties of Files That Compose the Backup ..................................... 82
Exporting Backup Files ...................................................................................... 84
Defining How the Backup Process Is Performed ............................................... 86
Backup Utility Commands and Options ............................................................. 87
To perform a backup of Panel hosting data, you need to execute the pleskbackup utility command that does the following:
1. Defines the data that need to be backed up.
2. Defines the way the backup process will be performed.
3. Defines properties of the files that will be contained in the backup.
4. Defines options for exporting the backup as a single file.
Note: Only the first component is obligatory; the others are optional.
The following sections explain the meaning and implementation of each component in detail.
The pleskbackup utility is located in $PRODUCT_ROOT_D/bin/pleskbackup where the $PRODUCT_ROOT_D is /usr/local/psa for RPM-based systems or /opt/psa on DEB- based systems.
To see a complete list of the pleskbackup commands and options, refer to the section Backup Utility Commands and Options (on page 87).
If the command execution succeeds, a backup is created in the default server backup location, or is exported to a file if exporting options were specified. For details on exporting options, refer to the section Exporting Backup Files (on page 84). If the command execution fails, a backup is not created.
You can perform advanced configuration of the backup operation through the file $PRODUCT_ROOT_D/admin/share/pmmcli/pmmcli-rc. For more details, refer to the section Defining How the Backup Process Is Performed (on page 86).
Backing Up, Restoring, and Migrating Data 73

Backup Objects: Hierarchy and Volume

Panel provides opportunities for backing up and restoring nearly all hosting data, which includes main Panel objects: administrator account, settings for Panel-managed services, reseller accounts, customer accounts, subscriptions, websites, databases and mail accounts. These backup objects are organized into a hierarchy where parent object is always an owner of its children. The hierarchy comprises of four levels: server, resellers, customers and subscriptions. The levels are such that a higher level includes objects on the lower levels but a lower level is completely separated from the higher objects.
You can create either a full or a partial backup. A full backup is the highest-level backup and includes all data related to a Panel installation. A partial backup includes only the desired Panel objects of any of the levels. For information on available options when creating a partial backup, refer to the section Specifying Data for Backing Up (on page 76).
Restoring a backup, in turn, can also be either full or partial. Full restoration recovers all data contained in a backup, and partial recovers part of this data. For information on available options when restoring data from backups, refer to the Defining Objects for Restoration (on page
92) section.
Each backup object includes the following:
Configuration defines the properties of the backup object and its descendants.  Content contains binary data related only to the backup object (website content and
content of mailboxes).
This table shows what data (configuration and content) are related to each backup object.
74 Backing Up, Restoring, and Migrating Data
Backup Object Type
Configuration
Content
server
This backup level includes the following:
Administrator information.  Web Presence Builder settings.
SSO settings.  IP addresses.  Database server settings.  DNS settings.  Mail server settings.  Antivirus and spam protection settings.
SSL certificates.  Reseller plans, hosting plans, and add-on
plans.
Information about administrator's subscriptions,
reseller accounts, customer accounts and websites.
Information about user roles.  Information about auxiliary users who can
access Control Panel.
Information about mail accounts and individual
settings for protection from spam and viruses .
Site isolation settings.  Settings for notification on system events.
License keys for Panel, virtual host templates, website content, error documents, log files, and content of mailboxes.
reseller
This backup level includes the following:
Reseller information.  Reseller's hosting plans.  Resource allotments and permissions for
operations in Panel.
Allocated IP addresses.
Information about customer accounts,
subscriptions, and websites with DNS settings.
Information about user roles.  Information about auxiliary users who can
access Control Panel.
Information about mail accounts and individual
settings for protection from spam and viruses.
Website content, error documents, log files, content of mailboxes.
Backing Up, Restoring, and Migrating Data 75
Backup Object Type
Configuration
Content
customer
This backup level includes the following:
Customer information.  Hosting plans to which the customer is
subscribed.
Resource allotments and permissions for
operations in Control Panel.
IP addresses used by customer's
subscriptions.
Information about websites with DNS settings.
Information about user roles.  Information about auxiliary users who can
access Control Panel.
Information about mail accounts and individual
settings for protection from spam and viruses.
Website content, error documents, log files, content of mailboxes.
subscription
This backup level includes the following:
Information about a subscription, its owner and
associated hosting plan.
IP addresses allocated to the subscription.  Resource allotments and permissions for
operations in Control Panel.
Information about websites with DNS settings.  Information about mail accounts and individual
settings for protection from spam and viruses.
Website content, error documents, log files, content of mailboxes.
76 Backing Up, Restoring, and Migrating Data

Specifying Data for Backing Up

(All)
Only web hosting settings
option: --only­hosting
Only mail
option: --only-mail
(All)
Only configuratio n
option: -c
(All)
Only configuratio n
option: -c
(All)
Only configuratio n
option: -c
Server
command:
server
(All)
Excluding resellers
options:
--exclude­reseller or
--exclude­reseller-file
Excluding customers
options:
--exclude-client
or
--exclude­client-file
Defining data that should be backed up includes the following:
1. Defining the backup level and, unless it is the server level, optionally, selecting which resellers, customers, or subscriptions should be backed up.
2. (Optional). Defining which resellers, customers, or subscriptions should be excluded from the backup.
3. (Optional). Restricting backup to either only mail content, web hosting content, or their configuration.
4. (Optional). Specifying that log files are excluded from backup.
Generally speaking, the data that can be backed up with one call of the pleskbackup utility are represented by any single cell of the following table.
Backing Up, Restoring, and Migrating Data 77
Excluding subscriptions
options:
--exclude-domain
or
--exclude­domain-file
All or selected resellers
command:
resellers­name
or
resellers­id
(All) / (All selected)
Example 1
Excluding resellers
options:
--exclude­reseller or
--exclude­reseller-file
Example 1*
Excluding customers
options:
--exclude-client or
--exclude­client-file
Excluding subscriptions
options:
--exclude-domain
or
--exclude­domain-file
All or selected customers
command:
clients­name
or
clients-id
(All) / (All selected)
Excluding customers
options:
--exclude-client or
--exclude­client-file
78 Backing Up, Restoring, and Migrating Data
Excluding subscriptions
options:
--exclude-domain
or
--exclude­domain-file
All or selected subscriptions
command:
domains­name
or
domains­id
(All) / (All selected)
Example 2
Excluding subscriptions
options:
--exclude-domain
or
--exclude­domain-file
Backing Up, Restoring, and Migrating Data 79
Example 1: With one call of pleskbackup, you can back up hosting data for several resellers (rows 5 or 6 in the table, depending on what is more convenient: to list resellers that should be included or those to be excluded) and restricting the backup data to configuration of web hosting on sites owned by the resellers or their customers (column 4 in the table).
To back up website hosting configuration of resellers with usernames reseller1 and reseller2, issue the following command:
pleskbackup resellers-name "reseller1 reseller2" --only-hosting -c
Example 2: With one call of pleskbackup, you can back up the mail configuration and content of mail accounts (column 5) for all subscriptions existing on the server (row 12).
To back up mail accounts with messages for all subscriptions:
pleskbackup domains-name --only-mail
The rest of this section explains each option in detail and provides examples of commands.
Defining backup level and selecting objects
To define the backup level and select backup objects, the commands of the pleskbackup utility are used.
If performing a selective backup, resellers, customers or subscriptions selected for the backup should be specified by their identifiers which are either usernames or IDs. The specification can be done in one of the following two ways:
Command line specification. The backup command takes object identifiers as arguments
separated with spaces.
File specification. The backup command takes the --from-file option which specifies
the file where the identifiers of objects are listed. The file must be in plain text format, and object identifiers are separated by line breaks (i.e., one identifier per line).
Note: If a command contains both specifications, file specification is used and the command line specification is ignored.
To back up all data related to Panel installation:
pleskbackup server
To back up all resellers, customers, or subscriptions:
pleskbackup <resellers|clients|domains>-<name|id>
For example, to back up all customer accounts:
pleskbackup clients-name
or
pleskbackup clients-id
80 Backing Up, Restoring, and Migrating Data
To back up several resellers, customers, or subscriptions defined in the
command line:
pleskbackup <resellers|clients|domains>-<name|id> [
<identifier1> [ <identifier2> ... [<identifier n>]]
For example, to back up three resellers defined in the command line:
pleskbackup resellers-name "johndoe janedoe josephine"
To back up several resellers, customers, or subscriptions listed in a file: pleskbackup <resellers|clients|domains>-<name|id> --from-file=<file>
For example,
pleskbackup resellers-name --from-file="etc/backup lists/backup"
Defining which objects should be excluded
Objects that should be excluded from the backup are specified by their usernames (reseller, customer accounts) or domain names (subscriptions). This can be done as follows:
Command line specification. The backup command takes objects identifiers as values of
the --exclude-<reseller|client|domain> option separated by commas.
File specification. The backup command takes the objects identifiers from the file
specified by the --exclude-<reseller|client|domain>-file option. The file must be in plain text format, and object identifiers are separated by line breaks (that is, one identifier per line).
Note: It is acceptable to use both specifications in one command. In such a case, all specified objects are excluded from the backup.
To back up all reseller accounts except for several selected resellers: pleskbackup resellers-name --exclude-reseller=<login1>,<login2>[,<login n>] or pleskbackup resellers-name --exclude-reseller-file=<file>
For example,
pleskbackup --resellers-name --exclude-reseller=johndoe,janedoe
or
pleskbackup --resellers-name --exclude-reseller-file="etc/backup lists/backup"
Backing Up, Restoring, and Migrating Data 81
To back up a selected reseller without several subscriptions belonging to them
or their customers:
pleskbackup --resellers-name <username> --exclude­domain=<name1>,<name2>,<name n>
or
pleskbackup --resellers-name <username> --exclude-domain-file=<file>
For example,
pleskbackup resellers-name johndoe --exclude­domain=example.com,example.net,example.org
or
pleskbackup resellers-name johndoe --exclude-domain-file="etc/backup lists/backup"
Restricting backup to only mail content, only hosting content, or only their configuration
The amount of backup data can be further narrowed to backing up either mail or physical hosting content and configuration by using the --only-mail or --only-hosting options, respectively.
Specifying the --only-hosting option results in backing up only website-specific data which includes the following, for each domain with physical hosting:
website content (including protected directories, web users, MIME types) web hosting configuration (including settings of anonymous FTP, log rotation, hotlink
protection, shared SSL, web users)
installed site applications databases subdomains
Specifying the --only-mail option results in backing up only mail-specific data that includes the following:
if used for the partial backup, for each domain included in the backup:
configuration of per-subscription mail settings
mail accounts
mailing lists
if used for the full backup, in addition to previous:
RBL protection settings
ACL white and black list configurations
The amount of backup data can also be narrowed in another way: by specifying that only configurations of the selected objects should be backed up. This specification is made by using the --only-configuration option.
Such backups are useful when the objects content is backed up by a third-party system.
82 Backing Up, Restoring, and Migrating Data
To back up mail configuration on subscriptions belonging to a customer: pleskbackup clients-<name|id> <name|id> --only-mail --configuration
For example,
pleskbackup clients-id 42 --only-mail --configuration
To back up websites content and hosting configuration on subscriptions
belonging to all resellers:
pleskbackup resellers-id --only-hosting
Excluding log files from back up
If Panel's log files related to the hosted objects are not required to be backed up, they can be excluded from the backup by using the --skip-logs option.
To back up the Panel configuration without log files:
pleskbackup server -c --skip-logs

Defining Properties of Files That Compose the Backup

Defining the properties of the files that will be contained in the backup includes the following:
1. Specifying that archives with backup object contents should not be compressed.
2. Specifying that a prefix should be added to the names of the backup files.
3. Specifying that backup files should be split into parts of the specified size.
Specifying that archives with backup object contents should not be compressed
By default, Panel saves backed up content to compressed .zip archives to save disk space when the backup is stored. However, restoring backups that contain compressed archives requires almost twice as much disk space as restoring those with uncompressed files. If you want to create your backups without compression, use the -z option in your backup command.
Specifying that a prefix should be added to the names of the backup files
In order to better distinguish files that were created during one backup session from another, pleskbackup adds a prefix to the backup file name. By default, it is backup, so every backup file name looks like backup_<file-name>.<ext>. The prefix in names of the files that compose a particular backup can be customized by using the --prefix option. The option's value will be added as a prefix to the names of files of the created backup.
For example, to create a backup of the server mail configuration so that all files in the backup have the prefix mail-friday:
pleskbackup server --only-mail --configuration --prefix="friday"
Backing Up, Restoring, and Migrating Data 83
Specifying that backup files should be split into parts of the specified size
The pleskbackup utility is capable of splitting backup files into parts of a particular size, which is extremely useful in cases when the file size is critical. Such cases could include the following:
if backups are burnt to DVDs, file size should not exceed approximately 4 Gbytes if backups are stored on the FAT32 file system, file size should not exceed approximately
4 Gbytes
if backups are stored on FTP, the FTP server may have its own restrictions on the size of
a single file transferred to the server
To make pleskbackup split the backup files to parts of a particular size, use the -s|--split option and specify the required size as the option value. For details on how to specify the size, refer to the section Backup Utility Commands and Options (on page 87). The default value used by pleskbackup if no custom size is specified is 2 Gbytes. The utility numbers file parts created as a result of a split by adding numerical suffixes to the file names starting from .1.
For example, to back up a subscription and split backup files into parts of no more than 700 Mbytes:
pleskbackup domains-name example.com --only-hosting --split=700M
84 Backing Up, Restoring, and Migrating Data

Exporting Backup Files

By default, pleskbackup stores backups in Panel's backup repository located on the server in /var/lib/psa/dumps/.
Panel is capable of exporting the created backup as a single .zip file in one of the following ways:
to stdout
to a local file system to an FTP server
To export the backup as a single file, use the --output-file option. Each particular export mode requires specific option values.
Important: After a backup is exported, pleskbackup removes it from the Panel's backup repository.
The exported file can also be created uncompressed and/or split into parts of a particular size, just like the files forming the backup in the repository (details (on page 82)).
Exporting to stdout
To export a backup as a file to stdout, use the --output-file option with the stdout value.
For example, to create a backup of a subscription with ID 1 and export it to stdout:
pleskbackup domains-id 1 --output-file stdout
Exporting to a local file system
To export a backup as a file to a local file system, use the --output-file option with a <full-path-to-file>\<file-name> value.
For example, to create a backup of a subscription with ID 1 and export it to the file domain1.tgz located at /usr/local/irregular-backups/ folder:
pleskbackup domains-id 1 --output-file=/usr/local/irregular­backups/domain1.tgz
Exporting to FTP server
To export a backup as a file to an FTP server, use either of the following options:
--output-file=ftp://<login>:<password>@<server>/<filepath>
--output-file=ftp://<server>/<filepath> --ftp-login=<ftp login>
--ftp-password=<ftp password>
You may want to use a passive mode FTP connection if a firewall prevents the export. For this, use the --ftp-passive-mode option.
Backing Up, Restoring, and Migrating Data 85
For example, to create backup of a subscription with ID 1 and export it to an FTP server example.com to the storage/backups/ directory, using johndoe as login and jjFh6gsm as password:
pleskbackup domains-id 1 --output­file=ftp://johndoe:jjFh6gsm@example.com/storage/backups
or
pleskbackup domains-id 1 --output-file=ftp://example.com/storage/backups -­ftp-login=johndoe --ftp-password=jjFh6gsm
86 Backing Up, Restoring, and Migrating Data

Defining How the Backup Process Is Performed

You can specify the following options for the backup operation:
1. Do not perform the backup if your server does not have specified free disk space.
2. Do not perform the backup if your server does not have enough free disk space to store
the backup content.
3. Temporarily suspend websites during backup.
4. Configure the backup utility to include more details in backup reports.
Specifying disk space requirements for the backup
You can prevent the start of the backup operation if your server has not enough disk space to complete it. To set the free disk space requirements, change the parameters in the file $PRODUCT_ROOT_D/admin/share/pmmcli/pmmcli-rc.
There are two ways to prevent the start of the backup operation:
Specify minimal free disk space on your server.
If the server does not have the specified disk space, Panel will not start the backup operation. Set the minimal free disk space in MB by changing the value of the FREE_DISK_SPACE parameter. Say, to prevent the backup if free disk space on the server is less than 100 MB, edit the line in the following way:
FREE_DISK_SPACE 100
Restrict the backup if your server does not have enough free disk space to store the
backup content. If this option is turned on, Panel calculates the future backup size and compares it with the free disk space on the server. If there is not enough disk space, Panel will not start the backup operation. Note that this option can significantly increase the backup time. To turn this option on, set the CHECK_BACKUP_DISK_SPACE to 1. To turn this option off, set the parameter to 0. Say:
CHECK_BACKUP_DISK_SPACE 0
Suspending websites
If your backup will include websites, we recommend that you suspend them during the backup process by using the --suspend option of the backup utility. This will help you avoid possible errors that may be caused by changes made to the site configuration or content during the backup.
The suspension is made as short as possible: each site is suspended only for the time it is being backed up: The site is started automatically as soon as its data are processed.
Backing Up, Restoring, and Migrating Data 87
Defining level of backup verbosity
Option
Verbosity
Example
no, -v, -vv
Low
To create a complete server backup with a low level of verbosity on Linux/Unix:
# opt/psa/bin/pleskbackup server
-vv
-vvv
Medium
To create a complete server backup with a medium level of verbosity on Linux/Unix:
# opt/psa/bin/pleskbackup server
-vv
-vvvv, ­vvvvv
High
To create a complete server backup with a high level of verbosity on Linux/Unix:
# opt/psa/bin/pleskbackup server
-vv
Command
Argument
Description
server
Backs up whole Plesk server.
There are three levels of backup verbosity:
Low: backup utility writes into a log and displays only general errors, such as syntax
errors (no or wrong command specified, invalid input parameters), runtime errors, unhandled exceptions, low disk space for backup and so on.
Medium: backup utility writes into a log and displays general errors and information on
backup stages.
High: backup utility writes into a log and displays general errors, information on backup
stages, debug information and messages sent to and received from the backup utility.
The verbose mode of the backup process is defined by the -v option:
To run a task on creating a complete server backup with a maximum level of
verbosity:
pleskbackup server -vvvvv

Backup Utility Commands and Options

Location
$PRODUCT_ROOT_D/bin/pleskbackup where the $PRODUCT_ROOT_D is /usr/local/psa for RPM-based systems or /opt/psa on DEB-based systems.
Usage
pleskbackup <command> [<arguments>] [<options>]
Commands
88 Backing Up, Restoring, and Migrating Data
Command
Argument
Description
resellers­name
[<login-1> <login-
2> <...> <login­n>]
Backs up all data for the resellers specified by logins.
Logins should be separated by spaces, and, if on Windows, enclosed in quotes.
Can be used with the --from-file option. In such case, resellers specified in the file are backed up and resellers specified as command arguments are ignored.
If no logins are specified and the -f option is not used, all resellers are backed up.
resellers­id
[<ID1> <ID2> <...> <IDn>]
Backs up all data for the resellers specified by IDs.
IDs should be separated by spaces, and, if on Windows, enclosed in quotes.
Can be used with the --from-file option. In such case, resellers specified in the file are backed up and resellers specified as command arguments are ignored.
If no IDs are specified and the -f option is not used, all resellers are backed up.
clients­name
[<login-1> <login-
2> <...> <login­n>]
Backs up all data for the customers specified by logins.
Logins should be separated by spaces, and, if on Windows, enclosed in quotes.
Can be used with the --from-file option. In such case, customers specified in the file are backed up and customers specified as command arguments are ignored.
If no logins are specified and the -f option is not used, all customers are backed up.
clients-id
[<ID1> <ID2> <...> <IDn>]
Backs up all data for the customers specified by IDs.
IDs should be separated by spaces, and, if on Windows, enclosed in quotes.
Can be used with the --from-file option. In such case, customers specified in the file are backed up and customers specified as command arguments are ignored.
If no IDs are specified and the -f option is not used, all customers are backed up.
domains­name
[<name-1> <name-2> <...> <name-n>]
Backs up all data for the domains specified by names.
Names should be separated by spaces, and, if on Windows, enclosed in quotes.
Can be used with the --from-file option. In such case, domains specified in the file are backed up and domains specified as command arguments are ignored.
If no names are specified and the -f option is not used, all domains are backed up.
Backing Up, Restoring, and Migrating Data 89
Command
Argument
Description
domains-id
[<ID1> <ID2> <...> <IDn>]
Backs up all data for the domains specified by IDs.
IDs should be separated by spaces, and, if on Windows, enclosed in quotes.
Can be used with the --from-file option. In such case, domains specified in the file are backed up and domains specified as command arguments are ignored.
If no IDs are specified and the -f option is not used, all domains are backed up.
--help
Displays help on the utility usage.
Option
Description
--exclude­reseller[=<login1>,<login2>,.. .]
Skips resellers with the specified logins during backup.
--exclude-reseller­file[=<file>]
Skips resellers listed in the specified file during backup.
--exclude­client=[<login1>,<login2>,...]
Skips customers with the specified logins during backup.
--exclude-client-file=<file>
Skips customers listed in the specified file during backup.
--exclude­domain[=<name1>,<name2>,...]
Skips domain with the specified names during backup.
--exclude-domain-file=<file>
Skips domains listed in the specified file during backup.
Option
Description
-v|--verbose
Shows more information about the backup process. Multiple -v options increase verbosity. For the maximum verbosity level, define 5 options.
-c|--configuration
Backs up only configurations of Plesk objects, excluding their content.
-s|-­split[=<integer>[K|M| G]]
Splits the backup files into parts of the specified size. The parts are numbered by appending numerical suffixes starting with .1.
Size is specified in Kbytes, Mbytes or Gbytes. If none is defined, size is interpreted as being in bytes.
If no argument is specified, a default value of 2 Gbytes is used.
-z|--no-gzip
Sets that object content is archived without compressing.
Exclude Options
General Options
90 Backing Up, Restoring, and Migrating Data
Option
Description
--only-mail
Backs up only mail configuration and content.
When used with the resellers|clients|domains-login|id commands, backs up configuration of domain-level mail system, and content and configuration of mail accounts.
When used with the server command, also backs up server-wide mail configuration.
Cannot be used with the --only-hosting option.
--only-hosting
Backs up only physical hosting configuration and Web site content, including site applications, databases and subdomains.
Cannot be used with the --only-mail option.
--suspend
Suspends domains during backup operation.
-f| --from-file=<file>
Backs up resellers|customers|domains listed in the specified file, ignoring those specified in the command line as arguments.
The file should be in plain text format and should contain a list of resellers|customers|domains, one per line.
Used only with the resellers-name, resellers-id, clients- name, clients-id, domains-name, domains-id commands.
Depending on the command, resellers|customers|domains are listed in the file by either logins or IDs.
--skip-logs
Sets that log files are not saved to backup.
--prefix=<string>
Adds a specified prefix to the backup file names.
Used to customize backup file name which is created with the backup prefix by default.
Option
Description
--ftp­login=<ftp_login>
Specifies FTP login that will be used for uploading backup file to the FTP server.
--ftp­password=<ftp_password
>
Specifies password that will be used for uploading backup file to the FTP server.
--ftp-passive-mode
Specifies that a passive mode FTP connection should be used.
Option
Description
--output-file
Exports backup as a single file to stdout and removes backup from Plesk repository.
FTP Options
Output File Option
Backing Up, Restoring, and Migrating Data 91
Option
Description
--output­file=<fullpath/filename>
Exports backup as a single file with the specified name to a local file system and removes backup from Plesk repository.
--output­file=<ftp://[<login>[:<passwor d>]@]<server>/<filepath>>
Exports backup as a single file to the specified FTP server and removes backup from Plesk repository.
The FTP_PASSWORD environment variable can be used for setting a password.
The --ftp-login and --ftp-password FTP options can be used for setting login and password.
In this section:
Defining Objects for Restoration ........................................................................ 92
Defining How the Restore Process is Performed ............................................... 98
Conflict Resolution Rules and Policies .............................................................. 99
Restoration Utility Commands and Options ....................................................... 120

Restoring Data

To perform restoration of Panel hosting data, you should execute the pleskrestore utility command that does the following:
1. Defines the Panel objects to be restored.
2. Defines how the restore process will be performed.
3. Defines conflict resolution rules and policies.
The following sections explain each component in detail.
The pleskrestore utility is located in $PRODUCT_ROOT_D/bin/pleskbackup where the $PRODUCT_ROOT_D is /usr/local/psa for RPM-based systems or /opt/psa on DEB- based systems.
To see a list of the pleskrestore commands and options, refer to the section Restoration
Utility Commands and Options (on page 120).
92 Backing Up, Restoring, and Migrating Data

Defining Objects for Restoration

Restoration levels specified with the -level option
Server
Resellers
Customers
Subscriptions
Selected with the ­filter option
Selected with the ­filter option
Selected with the - filter option
Backup file
<server>.xml | zip | tar
Full restoration
All reseller accounts
Selected reseller accounts
All customer accounts belonging to administrator
Selected customer accounts belonging to administrato r
All subscription s belonging to administrato r
Selected subscriptio ns belonging to administrat or
<reseller>.xml | zip | tar
Full restoration of a reseller account
All customer accounts belonging to reseller
Selected customer accounts belonging to reseller
All subscription s belonging to reseller
Selected subscriptio ns belonging to reseller
<customer>.xml | zip | tar
Full restoration of a customer account
All subscription s belonging to customer
Selected subscriptio ns belonging to customer
<subscription>.x ml | zip | tar
Full restoration of a subscription
Defining objects for restoration includes the following:
1. Specifying a source backup file.
2. Defining the level of restored objects.
3. Applying a filter on the specified level.
Generally speaking, the data that can be restored with one call of the pleskrestore utility are represented by any cell in the following table.
Backing Up, Restoring, and Migrating Data 93
Specifying a source backup file
The source backup file defined for restoration can be of one of the following types:
<info>.xml - backup metadata file, when restoring from backup located in Panel's
repository.
<backup>.<zip|tar> - archived backup file, when restoring from an exported backup.
For example, to restore the whole server backup, you choose a <backup repository root>/<server>.xml file, or an exported server backup file. To restore a client belonging to a reseller, you choose a <backup repository root>/resellers/<reseller ID>/clients/<client ID>/<client>.xml file.
Defining level of restored objects
Defining the level of restored objects allows you to narrow the amount of restored data according to your needs. For example, you may want to restore only subscriptions which belong to a customer or a reseller, skipping all other data not related to subscriptions.
To define the level of restored objects, use the -level option with an appropriate value. The option is required, so in cases when you do not need any narrowing but just wish to restore all data from a backup, define the level equal to the level of the file.
To restore entire server:
pleskrestore restore <backup repository root>/<server>.xml -level server
Note: When the whole server backup is restored, license keys are not restored by default. To restore license keys along with other server content, use the -license option in your restore command.
To restore entire server with license keys:
pleskrestore --restore <backup repository root>/<server>.xml -level server
-license
To restore all domains belonging to a reseller:
pleskrestore --restore <backup repository root>/resellers/<reseller ID>/<reseller>.xml -level domains
To restore all reseller accounts:
pleskrestore --restore <backup repository root>/<server>.xml -level resellers
94 Backing Up, Restoring, and Migrating Data
Applying filter to the specified level
In this section:
Backup File Structure ........................................................................................ 94
<info>.xml
Metadata files of full and server-level backups, one per backup, describe configuration and content of server, admin, and all their descendants.
To perform a more selective restore, use a filter (the -filter option) which selects particular objects of the specified level (resellers, customers, subscriptions) to be restored. The objects are specified by their names, which are domain names for subscriptions, and usernames for resellers and customers. The specification can be done as follows:
Command line specification. The restore command takes object identifiers as values of
the -filter option defined in the following string: list:<item1>,<item2>,...,<itemN>.
File specification. The restore command takes the objects identifiers from the file
specified as an argument of the -filter option. The file must be in plain text format, and object identifiers are separated by line breaks (that is, one identifier per line).
To restore two resellers from a server backup:
pleskrestore --restore <backup repository root>/<server>.xml -level resellers -filter list:JohnDoe,JaneDoe
or
pleskrestore --restore <upload directory>/<server backup name>.zip -level resellers -filter list:JohnDoe,JaneDoe
To restore two subscriptions owned by the server administrator:
pleskrestore --restore <backup repository root>/<server>.xml -level domains
-filter list:example.com,sample.org
To restore several subscriptions of a customer defined in a file:
pleskrestore --restore <backup repository root>/resellers/SandyLee/clients/JaneDow/<client>.xml -level domains - filter <path to the file>/restore-domains.txt
Backup File Structure
By default, all backups are created in a backup repository located on the Panel-managed server: in a repository specified by the DUMP_D variable defined in the /etc/psa/psa.conf configuration file
The repository is structured as follows, starting with the content of the repository root folder (we omit auxiliary files and folders which are irrelevant for backing up and restoring Panel data using pleskbackup and pleskrestore utilities).
Backing Up, Restoring, and Migrating Data 95
<content>.<zip|tar|tgz>
Archives with content of server and admin.
clients/
Directory containing the following backup data:
clients owned by admin or with no
owner
objects owned by the clients
Organization of the directory is the same as that of
<repository>/resellers/<resel ler ID>/clients/.
domains/
Directory containing the following backup data:
domains owned by admin or with
no owner
objects owned by the domains
Organization of the directory is the same as that of
<repository>/resellers/<resel ler ID>/clients/<client
ID>/domains.
resellers/
Directory containing the following backup data:
resellers objects owned by the resellers
<reseller ID>/
Directories containing backup data of particular resellers, one reseller per directory, and the objects owned by them.
The reseller ID stands for the reseller login name.
<info>.xml
Metadata files of the reseller backups, one file per backup, describe configuration and content of the reseller and the objects they own.
<content>.<zip|tar|tgz>
Archives with the reseller content.
domains/
Directory containing the following backup data:
domains owned by the reseller objects owned by the domains
Organization of the directory is the same as that of
<repository>/resellers/<resel ler ID>/clients/<client ID>/domains/.
96 Backing Up, Restoring, and Migrating Data
clients/
Directory containing the following backup data:
clients owned by the reseller objects owned by the clients
<client ID>/
Directories containing backup data of particular clients, one client per directory, and the objects owned by them.
The client ID stands for the client login name.
<info>.xml
Metadata files of the client backups, one file per backup, describe configuration and content of the client and the objects he owns.
<content>.<zip|tar|t gz>
Archives with the client content.
domains/
Directory containing the following backup data:
domains owned by the client objects owned by the domains
<internationa l domain name> <domain ID>/
Directories containing backup data of particular domains, one domain per directory, and the objects owned by them.
The domain ID is omitted if the domain IDN is less than 47 symbols.
<info>.xml
Metadata files of the domain backups, one file per backup, describe configuration and content of the domain and the objects it owns.
<content>
Other files and folders which contain domain contents, and its children contents and configurations.
Backing Up, Restoring, and Migrating Data 97
Files of each backup are placed in the repository folders according to the described structure.
f a partial backup is created, its files will be placed according to the location of the backup objects in the hierarchy. For example, if backing up domain example.com owned by reseller JaneDoe, its files will be located in the <repository root directory>/resellers/JaneDoe/domains/example.com/ folder. If backing up reseller, JohnDoe, who owns a domain joe.info and has one client, DukeNukem, who owns domain sample.org, the backup files will be located in the following folders:
1. <repository root directory>/resellers/JohnDoe/
2. <repository root directory>/resellers/JohnDoe/domains/joe.info/
3. <repository root directory>/resellers/JohnDoe/clients/DukeNukem/
4. <repository root directory>/resellers/JohnDoe/clients/DukeNukem/domains/sample.org
/
To distinguish files belonging to different backups of the same object, a specific prefix and suffix are added to the file names:
the backup is added by default, and, if you like, you can change it to your own on a per-
backup basis
a suffix designating the backup creation date is always added to each backup file, and
the date format is <yymmddhhmm>. For example, the files of a backup created on 6 April 2011, 8:58 PM will have the suffix 1104062058.
Panel is capable of exporting a backup as a single .tgz file. Each archive has the same structure as the repository, the only difference is that there is only one <info>.xml file on each level.
If a partial backup is exported, the resulting file structure is reduced from the top so that the highest level corresponds to the level of the highest backup object. For example, if a backup of a single customer (called, for example, SandyLee) is exported, the resulting file will have the following structure:
zip {
<sandy lee info>.xml
<content>.zip domains/
subscription1/
 ...
subscription_N/
 ...
}
98 Backing Up, Restoring, and Migrating Data

Defining How the Restore Process is Performed

When restoring data, you can also do the following:
1. Temporarily suspend websites during restoration.
2. Configure the restoration utility to include more details in backup reports.
Suspending websites
If you are going to restore websites, we recommend that you suspend them during the restoration by using the -suspend option. This will help you avoid possible errors in the restored sites that may be caused by changes made to the site configuration or content during the restoration.
The suspension is made as short as possible: each site is suspended only for the time it is being restored: The site is started automatically as soon as the data are processed.
Defining level of restore verbosity
pleskrestore works in one of the following verbosity modes:
1. Non-verbose mode. Default mode. The minimum level, only general errors are displayed, sauc as, syntax errors (no or wrong command specified, invalid input parameters), runtime errors and unhandled exceptions, and so on.
2. Verbose mode. Restore runs with verbosity level which additionally includes deployer errors, information about conflicts (read about restore conflicts in the section Conflict Resolution Rules and Policies (on page 99)), and so on. Enabled by adding the -verbose option to the pleskrestore command.
Backing Up, Restoring, and Migrating Data 99

Conflict Resolution Rules and Policies

Conflict is a situation when settings in a backup and settings in a destination Panel are such that restoring a backup object leads to an error or unpredictable Panel behavior.
Types of Conflicts
The restoration process can encounter several types of conflicts, as follows:
Timing conflicts. An object being restored might exist in the system and its last
modification date might be more recent than the date of backup. Or an object could be deleted from the system later than the backup was created.
Resource usage conflicts. There are two groups of resource usage conflicts:
Common resource usage conflict: The total amount of measurable resources after
restoration might appear to be over the limit for this particular user (e.g., disk space limit).
Unique resource usage conflict: An object being restored requires a unique
resource which is already being used by another object in the system or does not exist (e.g., domain).
Configuration conflicts. It might happen that the configuration being restored is not
enabled on the destination server. Two situations can arise here:
Configuration options are not enabled for the domain.
Required configuration options are not available (e.g., site applications are not
available for the customer, database server is not configured on the host, IP address is not allocated to the reseller, etc.)
Conflict Resolutions
The following conflict resolutions options are possible:
Overwrite. Means that all objects will be restored from the backup files regardless of
their current presence in the system. Overwrite works as follows:
If an object/setting from backup does not exist in Panel, it is created.
If an object/setting from backup exists in Panel, it replaces the existing object/setting.
If an object/setting exists in Panel but is missed in a backup, the existing object/setting
remains.
Proceed with current. Means that objects that are currently present in the system will
not be affected by the restoration process. The restoration process will move to the objects belonging to that one, not touching the object itself.
Do not restore. Means that the objects that are currently present in the system or were
deleted after the backup will not be restored with the lower level objects.
Automatic. Means that configuration option that should be enabled for domain is
enabled automatically.
100 Backing Up, Restoring, and Migrating Data
Overuse. Means that objects are restored even when the resources are overused. Can
be applied only to objects that belong to a reseller who is working in the oversell mode.
Rename. Means that unique resources for the restored domain are reassigned with the
specified name, existing in the system (mapping).
Conflict Resolution Policies and Rules
Depending on the scope of a conflict resolution, we distinguish between conflict resolution rules and policies:
Rule defines the way a specific single conflict should be resolved. Policy defines the way all conflicts of a particular type should be resolved.
Conflicts Resolving Mechanism: Default Policies, Custom Policies, and Rules
The restoration utility brings a set of default, hard-coded conflict resolution policies, which are as follows:
for timing conflicts - Overwrite for common resource usage conflicts - Overuse for unique resource usage conflicts - Do not restore for configuration conflicts - Automatic
The default policies are always applied during restoration and cannot be changed or overridden.
Applying default policies may not resolve all the conflicts that occur. In such cases, the person performing the restore should define additionally custom rules and/or policies that resolve the remaining conflicts. Custom rules and policies are defined in an XML format as described in the section Resolutions Description Format (on page 103).
A simplified presentation of conflict resolving during restore is as follows:
1. Administrator runs pleskrestore with specific parameters.
2. pleskrestore detects the conflicts that have occurred and resolves them using the
default policies.
3. pleskrestore checks if any conflicts remain unresolved.
If all conflicts are resolved, the restoration continues.
4. pleskrestore stops the restoration and, if run in debug or verbose mode, returns a detailed description (in XML format) of each remaining conflict.
5. Based on the returned description of the conflicts, the administrator creates a file that defines a resolution for each conflict (with rules) and/or in bulk (with custom policies).
6. The administrator runs the pleskrestore utility with the --conflicts-resolution option and the file created in the previous step as its argument.
7. pleskrestore detects the conflicts that have occurred and resolves them using the default policies.
Loading...