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.

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 variables and their meaning for addon domains and subdomains - i.e., when the web_files node is under an addon domain or subdomain node:

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.

Specifying the path to the databases

Plesk Migrator is able to copy MySQL/MariaDB 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