Search

Language:  
Search for:

  • Article for your preferred language does not exist. Below is international version of the article.
Available article translations:

How to move from third-party control panels to the Parallels Plesk 11.5

Article ID: 117755, created on Oct 7, 2013, last review on Sep 30, 2014

APPLIES TO:
  • Parallels Plesk
  • Parallels Plesk Automation 11.5

Abstract

This document describes the process of transferring domains from any third party panel to Parallels Plesk (Plesk), provides an overview of the general Plesk backup structure, and provides simple examples to get you started.

Introduction

The easiest way to move domains from third-party hosting control panels to Plesk is to make domain backups using the native tools of original panel. You can then convert the dump to the appropriate format for Plesk and restore this dump on the target machine where Plesk has been installed.

A full list of migration steps will include:

  1. Making a backup copy of the original domains
  2. Converting the original backup to a Plesk dump
  3. Packing the dump to a ZIP archive in Windows, or a .tar in Unix
  4. Importing the dump to Plesk (in this stage, the converted dump is checked for compliance with Plesk's backup rules)
  5. Restoring the imported dump

To prepare a dump in Plesk format, you will need to understand basic Plesk terms and objects.

The basic term of the Plesk model is “Subscription”. A Subscription determines customer permissions, limits, and hosting type. A Subscription has at least one domain, but can also contain add-on domains (with any arbitrary name and settings) and subdomains (with names that contain the parent domain name). All these domains will be moderated by the Subscription owner. On transfer, if several domains belong to one person and require the same payment plan, limits and permissions, these domains may be joined to single Subscription.

The Plesk model also includes such terms as “Client” and “Reseller”. These objects can have special limits and permissions and manage their own subscriptions. A Reseller can also control and manage its own clients.

Backup Object: Hierarchy and Volumes

Plesk provides opportunities for backing up and restoring nearly all hosting data, which includes its major objects: the Administrator account, reseller accounts, client accounts, domain accounts, mail accounts, databases, web sites, and subdomains. These backup objects are organized into a strict hierarchy, where a parent object is always an owner of its children. The hierarchy is as follows:

As you can see on the diagram, Plesk backup objects have 4 levels: server, resellers, clients and domains. 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.

Users can create either a full or partial backup. A full backup is the highest-level backup, including all Plesk data: server, admin and all descendant backup objects. A partial backup only includes the backup objects you need, of any level. More information on creating a full or partial backup can be found in: “Defining data for backup".

Similarly, restoring a backup can be either full or partial. A full restore revives all data contained in a backup, while partial restores a part. For more restore options, see: “Defining objects for restore section".

As mentioned, each backup object has its own data. This data consists of backup object configuration and content:

  • Configuration defines the properties of the backup object and its descendants
  • Content contains binary data related to the backup object (database backups, mail attachments, etc.).

This means that, for example, a client configuration includes the configuration of the domain he/she owns, but the content is completely independent.

This table shows what data (configuration and content) is related to each backup object.

Backup Object Type Own Configuration Own Content
server Settings of server-level services (mail and database servers, SSO, application vault, spam filters and antivirus), server preferences, Sitebuilder configuration, Plesk account templates, license keys, certificates, interface preferences, Plesk billing settings. License keys, custom button icons, Plesk skins, Plesk locales, Web application packages, custom templates of Apache configuration files.
admin Personal Plesk Administrator information.
reseller Personal reseller information, limits and permissions on resources, IP pool and Web application pool configuration, personal domain and client templates settings, custom buttons settings. Virtual host templates, custom button icons.
client Personal client information, limits and permissions on resources, IP pool and site application pool configuration, personal domain and client templates settings, custom buttons settings. Virtual host templates, custom button icons.
domain Resource usage limits, permissions, domain-level service settings (IP address, mail system, mailing lists, DNS, tomcat applications, traffic statistics), custom button and domain alias settings, domain administrator personal information, SSL certificates, hosting type settings. Mailing lists, tomcat applications, custom button icons.
mailuser Personal mail user information, permissions, mailbox settings, mail aliases, forwarding settings, mailgroup settings (only for mailgroup accounts), autoresponders configuration, addressbook (horde turba), SpamAssassin/drweb settings, custom buttons settings. Mail box content, autoresponder attachments, SpamAssassin files, custom button icons.
database Database server settings and database user settings. Database dump.
phosting System user account settings, scripting settings, Web applications settings, Frontpage user credentials, log rotation settings, anonymous FTP settings, additional FTP accounts, list of web-protected site locations, list of domain web users, subdomain settings, web statistics settings, hotlinking protection settings, performance and shared SSL settings. Virtual host content, content of installed Web applications, virtual directories content, web user home directories content.
subdomain System user account information, scripting options, Web applications list, hotlink protection settings, protected directory settings, and shared SSL settings. Content of virtual "sub-host", content of installed Web applications, custom button icons.

Backup Logical Structure

By default, all Plesk backups are created in the Plesk backup repository located on the Plesk server:

  • In Plesk for Linux/Unix, the repository location is specified by the DUMP_D variable defined in the /etc/psa/psa.conf configuration file
  • In Plesk for Windows, the repository is located in the %plesk_dir%\Backup folder, where %plesk_dir% is the environment variable specifying the directory where Plesk is installed (if installed to default locations, it is "C:\Program Files\Parallels\Plesk\")

The repository is structured as follows, starting with the content of repository root folder (we omit auxiliary files and folders which are irrelevant for backing up/restoring Plesk data using the pleskbackup/pleskrestore utilities):

  • <info>.xml - Metadata files of full and server-level backups, one per backup, describes configuration and content of server, admin, and all their descendants
  • <content>.<zip|tar|tgz> - Archives with content of server and admin
  • [clients] - Directory containing clients owned by admin or having no owner, and objects owned by the clients. The organization of the directory is the same as that of "<repository>/resellers/<reseller_id>/clients/".
  • [domains] - Directory containing domains owned by admin or having no owner, and objects owned by the domains. The organization of the directory is the same as that of "<repository>/resellers/<reseller_id>/clients/<client_id>/domains/".
  • [resellers] - Directory containing resellers and 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 she owns.
      • <content>.<zip|tar|tgz> - Archives of reseller content.
      • [domains] - Directory containing domains owned by the reseller and objects owned by the domains. Organization of the directory is the same as that of "<repository>/resellers/<reseller_id>/clients/<client_id>/domains/".
      • [clients] - Directory containing clients owned by the reseller and 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|tgz> - Archives with the client content.
          • [domains] - Directory containing domains owned by the client and objects owned by the domains.
            • [<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.

The files of each backup are placed in the repository folders according to the described structure.

If a partial backup is created, its files will be placed according to where the backup objects are in the hierarchy. For example, if you are backing up the domain example.com which is owned by the reseller JaneDoe, its files will be located in the "<repository>/resellers/JaneDoe/domains/example.com/" folder. If you are backing up the reseller JohnDoe, who owns a domain joe.info and has one client DukeNukem who owns the 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, specific prefixes and suffixes are added to the file names:

  • The backup prefix is added by default, and can be changed on a per-backup basis
  • The suffix designating the backup creation date is always added to each backup file. The date format is <yymmddhhmm>. For example, files of a backup created on March 8, 2009, 1:30 am will have the suffix 0903080130.

Plesk can export backups as a single file (.tgz in Linux/Unix and .zip in Windows). Each archive has the same structure as the repository. The only difference is that there is only one <info>.xml file on each level.

When 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 single client (called, say, SandyLee) backup is exported, the resulting file will have the following structure:

zip {
    <sandy lee info>.xml
    n*<content>.zip
    domains/
    domain1/
    ...
    domainN/
        ...
}

Structure of meta-files (*_info_*.xml)

Info-files must meet the rules described in the schema documents (XSD). Plesk validates each backup before restoration and when a dump is imported. Dumps which have at least one part which does not meet the dump schema cannot be restored or imported to Plesk.

The full dump schema is described in plesk.xsd and pmm-common.xsd.

The info-file must be encoded in UTF-8. Some attributes and node values use base64 encoding for special symbol escaping, while others use CDATA blocks. If some data contains XML special characters and Backup Manager expects these data in a plain format, CDATA block must be used.

Info-files contain the following information:

  • Dump version - used on import and pre-deploy stage to convert old dumps to the current format
  • Agent name - to know which conversion rules to apply
  • Dump info - to show a description in the UI
  • Metadata of hosting objects provisioned by the Plesk, such as domains, mailboxes, server settings, etc.

The full dump XML can contain server, reseller, client and domain, but any of them can be omitted. As a result, you can create a dump of server settings only, one paticular domain, or even client account settings without domains. The structure of these objects' metadata is more strict. Some of them cannot exist without their related objects. The order of description nodes in XML is important too - XML with valid relations but the wrong node sequence will be considered invalid when it is checked by the XSD schema.

Content of the .discovered folder

Each server, reseller, client or domain dump has service folder named ‘.discovered’, which keeps meta information of the dump itself. Information from the .discovered folder is used to get a list of dumps available on the corresponding level for a particular user. Here we get the cached dump part size (including nested dumps size), detect dump relations (belongs to…, contains also…), type (full or partial, server, client or domain) and status (can be used for restoration or not, or can be restored with some issues).

A backup with damaged .discovered content cannot be completely restored.

A feature is being planned to automatically create .discovered content.

Content packing

The info-file can contain links to content archives in the dump. On restoration, the deployer application will process these archives and extract their content using the rules described in the info-file.

Links and rules are provided by the ‘cid’ elements of the ‘content’ element (see XSD schema). The content of some hosting objects, such as web hosting content, can be packed into several archives or a single one. For each archive, we must create the cid element with information about the archive (file name, relative path in the dump, unpacked size, type of content).

Depending on the cid type, the dump deployer will use different restoration paths and apply different permissions. All the types are listed in XSD. You can pack the original hosting content to separate archives and each one will be processed with individual rules.

Some cid elements can be consolidated in one archive to improve performance. This method used to pack all the content to a single archive, but restore its different parts using different rules. The main requirement here is to have one cid for the physical archive file and any number of referred cids of other types to this one. By setting the offset attribute for a particular referred cid, we can set a concrete folder in the archive which will be extracted on restoration. There is another important rule for using referred cids: if some content cid has referrers, only the referrer’s content will be restored - not the whole archive.

If the schema with referrers is too complex and performance is not so important, you are free to not use referrers, but instead work with small separate archives.

In the table below, you can see the paths where each type of domain content will be restored on the Plesk environment inside the hosting root (by default "C:\inetpub\vhosts").

Content type Path to restore
docroot <domain-name>/. www-root-folder is “httpdocs” by default, but can be overwritten in domain settings
docroot_ssl <domain-name>/httpsdocs
cgi <domain-name>/cgi-bin
vhost <domain-name>
user-data <domain-name>
apache-files <domain-name>
error_docs <domain-name>/error_docs
logs <domain-name>/logs
ftp_pub <domain-name>/anon_ftp/pub
ftp_incoming <domain-name>/anon_ftp/incoming
private <domain-name>/private
statistics <domain-name>/.plesk/statistics/<domain-name>
webstat <domain-name>/.plesk/statistics/<domain-name>/webstat
webstat_ssl <domain-name>/.plesk/statistics/<domain-name>/webstat-ssl
ftp_stat <domain-name>/.plesk/statistics/<domain-name>/ftpstat
anon_ftpstat <domain-name>/.plesk/statistics/<domain-name>/anon_ftpstat

The same table for subdomains goes below.

Content type Path to restore
docroot <domain-name>/. sub-www-root-folder is subdomain name by default, but can be overwritten in domain settings
docroot_ssl <domain-name>/httpsdocs
cgi <domain-name>/cgi-bin
statistics <domain-name>/.plesk/statistics/
webstat <domain-name>/.plesk/statistics//webstat
webstat_ssl <domain-name>/.plesk/statistics//webstat-ssl
ftp_stat <domain-name>/.plesk/statistics//ftpstat
anon_ftpstat <domain-name>/.plesk/statistics//anon_ftpstat

In the simplest scenario, all domain content can be packed to a single archive and described with the cid type “vhost” or “user-data”. This content will be extracted as-is with user permissions to the domain hosting root.

Dump limitations

Since the dump hierarchy uses real domain names as file and folder names, you may exceed the maximum path length. To resolve this problem, trim long file and folder names and add an underscore plus a unique digit. The new name summary length must be 47 characters long. Example:

original file name:    myveryverylooooooooooooooooooooongdomainname.com
modified file name:    myveryverylooooooooooooooooooooongdomainname._1

The same rule is used for customers and resellers, but the length of the corresponding files and folders is limited to 25 characters.

Dump agent sample

The backup agent in Plesk for Windows presents in binary form, but the agent in Plesk for Unix is written on Perl programming language and is available in plain format. The source of Perl agent is easily accssed and its principles are similar to the agent for Windows. As a result, it can show all dump aspects in general and in detail.

To find Unix agent source on the machine where you have installed Plesk for Unix, go to /usr/local/psa/PMM/agents, where you will find dump creation modules (general is PleskX.pm), and find /usr/local/psa/admin/bin/plesk_agent_manager, which is a main executable file to process the command line and run the dump operation.

Windows source can be accessed using special disassembly tools, e.g. Resharper.

Dump restoration

Before dump restoration, do not forget perform the following steps in configuring Plesk:

  • Register the Plesk instance with a license key
  • Assign IP addresses and their types (shared/exclusive) to the target machine
  • Register a remote DB server if you plan to use one

To restore the backup, there are two possible methods:

  1. Using the Plesk GUI, import the dump and restore it with the restore wizard. This process cannot be automated. For a large number of domains, it may be sensible to pack them into a single dump to minimize intermediate operations such as importing.
  2. Using the command line utility “pleskrestore”. This is suitable for an automated deployment. No pre-deployment actions are required.

For more information on the pleskrestore utility, visit the following page: http://download1.parallels.com/Plesk/PP11/11.0/Doc/en-US/online/plesk-win-advanced-administration-guide/

Sample deployment command:

cd ""%plesk_dir%\bin"
pleskrestore.exe --restore C:\sample-dump.zip -level domains -verbose -debug -ignore-sign

Sample dump

In the attachment to this document, there is an archive file sample-dump.zip with a simple but valid dump. The dump contains the content and basic configuration of web hosting for one domain with a subdomain.

This dump was created based on a real backup of a Plesk instance with one domain. The original backup is also attached to this document (real-plesk-dump-sample.zip).

You can look at both, but we will use the simple truncated version below to understand the basics.

For simplicity, we do not consider the configuration of mail, FTP, databases or other aspects. Instead, we focus on web hosting and its basic parameters, content and DNS configuration. All other aspects will be configured with the Plesk default settings.

The dump archive contains the following files:

[.discovered]
    [bkp_info_1309271259]
        dump_full
        GUID_AA445A06-CA29-4909-B3E1-209BBD660B63
        objectid_admin
        owner_AA445A06-CA29-4909-B3E1-209BBD660B63
        ownertype_server
        status_OK
[domains]
    [example.com]
        [.discovered]
            [bkp_example.com_info_1309271259]
                dump_part
                GUID_A3162229-60D2-463E-9BFF-B27FF95EC96C
                objectid_example.com
                owner_AA445A06-CA29-4909-B3E1-209BBD660B63
                ownertype_server
                status_OK
        bkp_example.com_info_1309271259.xml
        bkp_example.com_user-data_1309271259.zip
bkp_info_1309271259.xml

As you can see from the listing above, the general service files and folders have the same prefix (bkp) and suffix (timestamp 1309271259) in the name. This is important because these marks are used to distinguish between certain backups and track relations.

The file “bkp_info_1309271259.xml” is a general entry point for the content deployer. This file contains links to the child dumps (domain dumps, since in this sample there are only one domain). In reality, this file can also contain server settings, admin account configuration, certificates, and the Plesk license description.

In the “.discovered” folder, the current dump level characteristics such as dump type, relations, owner and status are described. Normally, the status will always be OK.

Currently, Plesk does not support the restoration of a domain dump if a subscription with the same name does not already exist. As a result, we always need to create the server dump XML, even if it only contains links to child dumps. Therefore, you can use the root XML file and .discovered content from this sample dump as a base and simply add the new domain-info nodes to the root XML file to create links to child domain dumps.

Domain dumps are located in the “domains” folder. Each domain dump is in a separate folder named after the domain in ASCII (use IDN rules to represent national symbols in ASCII).

The file “bkp_example.com_info_1309271259.xml” contains a description of the domain “example.com”, including its hosting settings, DNS records, and system user credentials.

While migrating to Plesk, it is possible to keep the original IPs for domains. An IP-mapping file must be provided on restore in this case. However, to skip this step you can replace these IPs with the target IPs on the dump preparation stage. Fill out the “ip” node content in the domain XML when the backup is converted to the Plesk format. An “exclusive” type IP can only be assigned to one domain. You can assign IPv4, or v6, or both.

The node “webspace-status” manages the state of web hosting (enabled/disabled).

The node “status” controls the state of whole subscription.

The node “phosting” defines physical hosting settings, including the system user account, content description, available scripting on domain, and the IP for web hosting.

Notice the element content with the child element cid. This is a link to the domain webspace content archive (which resides in the same folder). If this content node is not present, no content will be restored for the domain - just the configuration.

The node “sites” can contain zero or more subdomains.

More information on XML node definitions can be found in the comments of the dump schema files (plesk.xsd and pmm-common.xsd).

Database dump

On Windows, Plesk can deploy MSSQL and MySQL databases.

Plesk uses a native mysqldump utility to backup and restore MySQL databases. As a result, a MySQL dump of a database managed by a third-party hosting panel must be made in mysqldump format.

For MSSQL databases, Plesk supports two dump types: SQL-script and native MSSQL dump format. Native dump format requires local MSSQL instance on the target machine. To transfer MSSQL databases, the following solutions can be used:

  • Move the local or remote database content using the SQL-script dump format
  • Move the database content in the native MSSQL dump format to the MSSQL instance (installed on the same machine where Plesk is installed)
  • Do not move the database content, but keep it on the source machine. Only transfer the database connection settings, to register these databases as remote databases on the target Plesk instance. This is the fastest solution for transferring, but requires you to keep the source databases as they are and makes native dump usage impossible in future backup operations on target machine. The same solution of transferring the database configuration without content can be applied to MySQL databases.

For transfer from third-party environment, the most convenient way is to transfer connection settings only. However, if you want to have an MSSQL backup in native format in the future, consider SQL-script backup. Using an MSSQL native dump for transfer is generaly not an option, since this process requires a local MSSQL instance.

Database transferring must meet the following requirements:

  1. Each database server type present on the source must be configured on the target machine before transferring
  2. While configuring database servers on the target machine, you must provide credentials of the admin user for each database server. This user must be able to create databases and other users. In the case of a remote database server, the admin user must be granted remote access from at least the target Plesk machine where you plan to restore the content.

With this document, there are two samples provided:

  1. real-db-dump-sample.zip - Dump of a real Plesk domain with databases
  2. sample-db-dump.zip - Trimmed version of the real dump to illustrate a simple case of database content deployment

Let's consider the sample-db-dump.zip content.

In "domains/example.com/db_example.com_info_1309301213.xml", there are descriptions of a domain with a subdomain and 3 databases: a local MySQL database, a local MSSQL database and a remote MySQL database.

To restore remote databases without transferring their content (ie. to register them in Plesk), you must set the environmental variable ""PLESK_MIGRATION_MODE = 1" in the same shell session where the pleskrestore utility will be executed. If you do not, database content will be missing.

In the example database, “remote_db” has no inner content block and uses an external IP, so it will be processed as a remote database on restore. With the PLESK_MIGRATION_MODE environment variable set to 1, the database will be attached to the Plesk environment without moving the content. If you start to add the content block to this database and do not set the PLESK_MIGRATION_MODE variable, it will be processed in the same way as a local database (ie. content from archive will be deployed on target server - the remote DB server in this case).

Each database in the example has one user. Additionally, there is another user in the “dbusers” block named “any_local_mysql”, who is granted access to all local MySQL databases created under the current domain.

Attachments

Search words:

rename




c81e59b61af9dca603ba03b14aabe968 56797cefb1efc9130f7c48a7d1db0f0c b2231b0275a8ff26de8dfbae19ed2984 b315de483b3ce496b93860f954cd3118 caea8340e2d186a540518d08602aa065

FEEDBACK
Was this article helpful?
Tell us how we may improve it.
Yes No
 
 
 
 
 
 
Server Virtualization
- Parallels Cloud Server
- Parallels Containers for Windows 6.0
- Parallels Virtuozzo Containers
Automation
- Parallels Automation
- Parallels Automation for Cloud Infrastructure
- Parallels Business Automation Standard
- Parallels Virtual Automation
- Parallels Plesk Panel Suite
- Web Presence Builder
- Parallels Plesk Automation
- Parallels Small Business Panel
- Value-added Services for Hosters
- Parallels Partner Storefront
Services & Resources
- Cloud Acceleration Services
- Professional Services
- Support Services
- Training & Certification