The hosting description file can be written in the YAML or JSON format, and contains the list of clients, subscriptions, addon domains, mailboxes, etc. to be transferred from the source server. You can find sample hosting description files here. This topic describes how to configure a number of commonly used parameters to ensure that the migration is successful.

Specifying the path to the web content data

To specify the path to the web content data, both on the source server and the destination server, use the following parameters in the subscriptions section:

  • source_webspace_root - The absolute path to the directory containing all files available to the customer on the source server. Can be specified on the subscription level only (e.g., /home/vhosts/example.com).
  • source_document_root - The absolute path to the directory containing only the files served via HTTP. Can be specified on the subscription, addon domain, or subdomain levels (e.g., /home/vhosts/example.com/httpdocs).
  • target_document_root - The directory that will contain the files served via HTTP on the destination server. The path is relative to subscription’s root directory on the destination server. Can be specified on the subscription, addon domain, or subdomain levels (e.g., data/www. If the domain name is example.com, and the virtual hosts directory in Plesk is /var/www/vhosts, the absolute path to the document root directory on the destination will be /var/www/vhosts/example.com/data/www). If left unspecified, the Plesk default value will be used.

Note: If the configuration file does not contain the access information for the source server, the source_webspace_root and source_document_root paths will be treated as local on the destination server.

If you need to prevent specific directories or files from being migrated, use the exclude directive with the source_webspace_root and source_document_root parameters. For example:

subscriptions:
  - name: example.com
    source_webspace_root:
      path: /home/vhosts/example.com
      exclude:
        - /bin
        - /logs

The syntax for writing the exclude rules is identical to that used by the rsync tool. Refer to the rsync documentation - see the Include/Exclude Pattern Rules section for more information.

If you need to specify exactly in which directory on the destination server the web content from a specific directory on the source server will be placed, use web file mapping. For example:

subscriptions:
  - name: example.com
    target_document_root: data/www
    web_files:
      - source: /home/vhosts/example.com
        target: "{webspace_root}"
      - source: /home/vhosts/example.com/httpdocs
        target: "{document_root}"

The target directive is used to specify either an absolute path on the destination server, or a format string containing one or more template variables from one of the tables below.

Template variables and their meaning for subscription - i.e., when the web_files node is directly under a subscription node:

Template variable Details Applicable to
{anon_ftp_incoming} Path to directory available for upload by anonymous FTP Linux only
{anon_ftp_pub} Path to directory available for reading by anonymous FTP Linux only
{cgi_bin} Path to cgi-bin directory of subscription Unix only
{document_root} Path to document root of subscription - directory available by HTTP Linux and Windows
{logs} Path to directory with logs (Apache access and error logs, etc) Linux and Windows
{main_domain_private} Private directory of main domain Windows only
{main_domain_statistics} Statistics directory of main domain (AWStats/Webalizer/etc) Windows only
{protected_dirs} Path to directory with settings of protected directories Linux only
{ssl_document_root} Path to secure document root of subscription - directory available by HTTPS Windows only
{statistics} Path to directory with statistics files (AWStats/Webalizer/etc) Linux only
{webspace_idn} Name of subscription encoded in punycode Linux and Windows
{webspace_root} Path to subscription root Linux and Windows
{webspace} Name of subscription Linux and Windows

Template variables and their meaning for addon domains and subdomains - i.e., when the web_files node is under an addon domain or subdomain node:

Template variable Details Applicable to
{cgi_bin} Path to cgi-bin directory of addon domain/subdomain Linux only
{document_root} Path to document root of addon domain/subdomain Linux and Windows
{logs} Path to directory with logs (Apache access and error logs, etc) of addon domain/subdomain Linux only
{protected_dirs} Path to directory with settings of protected directories of addon domain/subdomain Linux only
{site_idn} Name of addon domain/subdomain encoded in punycode Linux and Windows
{site} Name of addon domain/subdomain Linux and Windows
{statistics} Path to directory with statistics files (AWStats/Webalizer/etc) of addon domain/subdomain Linux and Windows
{webspace_anon_ftp_incoming} Path to directory available for upload by anonymous FTP of parent subscription Linux only
{webspace_anon_ftp_pub} Path to directory available for read by anonymous FTP of parent subscription Linux only
{webspace_cgi_bin} Path to cgi-bin directory of parent subscription Linux only
{webspace_document_root} Path to document root of parent subscription Linux and Windows
{webspace_idn} Name of parent subscription encoded in punycode Linux and Windows
{webspace_logs} Path to directory with logs (Apache access and error logs, etc) of parent subscription Linux and Windows
{webspace_protected_dirs} Path to directory with settings of protected directories of parent subscription Linux only
{webspace_root} Path to subscription root Linux and Windows
{webspace_ssl_document_root} Path to secure document root of parent subscription - directory available by HTTPS Windows only
{webspace_statistics} Path to directory with statistics files (AWStats/Webalizer/etc) of parent subscription Linux only
{webspace} Name of parent subscription Linux and Windows

Specifying the path to the mail content data

The mechanism of transferring the mail content from the source to the destination server works differently on Linux and on Windows.

On Linux, you need to specify the information about the mailboxes to be migrated in the mail_users section:

mail_users:
- name: johndoe
  password: 123qwe
  directory: /var/qmail/mailnames/johndoe

where “directory” specifies an absolute path to where the mailbox content is stored on the source server, or where it was placed after being manually moved to the destination server.

On Windows, nothing needs to be specified in the hosting description file. All mail content will be migrated using the Plesk backup and restore mechanisms.

Note: On Windows, Plesk Migrator does not have the ability to import mail content that has been manually moved to the destination server. For mail content to be migrated, access to the source server is necessary.

Specifying the path to the databases

Plesk Migrator is able to copy MySQL and Microsoft SQL Server databases when migrating from other panels. There are two ways to copy database content:

  • Copy the content directly if access to the database server is provided.
  • Restore the content from a database dump file.

To copy the content directly from a database server, it must be listed in the Plesk Migrator configuration file, and access information for the server must be provided. Use the server parameter in the databases section:

databases:
  - server: mysql-db
    name: wordpress_9
    users:
    - login: exdbuser1
      password: 123qwe
  - server: mssql-db
    name: drupal_2
    users:
    - login: exdbuser2
      password: 123qwe

or

- name: wordpress_9
  dump: wordpress_9.sql
  users:
    - login: exdbuser1

For restoring the content from a database dump file, the dump must be created in a specific format:

  • For MySQL, the dump can be created, for example, with mysqldump utility.
  • For Microsoft SQL Server, use the T-SQL construct “BACKUP”.

To restore a dump, specify the dump option, like this:

- name: wordpress_9
  dump: wordpress_9.sql
  user:
    login: exdbuser1

Note: Migrating Microsoft SQL Server databases is only possible if the hostname of the Microsoft SQL Server instance on the source server can be resolved from the destination server.